Announcing Inch

As I pointed out in my previous post, documentation sometimes seems like the step-child in code metrics, static analysis and – last but not least – awareness. My frustration regarding this matter let to the creation of a command-line tool to help people improve the documentation of their Ruby projects.

Inch analyses your code and inline-docs. In a way, it is a documenation measurement tool, although it does not measure coverage. Let’s see what that means:

Grades instead of scores

As you can see in the screenshot above, Inch gives grades (A,B,C) to each class, module, constant or method in your codebase. It also assigns a special grade (U) to undocumented objects.

Using these grades instead of percentage scores has some advantages:

• They are less rigid than percentages.
• You can get an ‘A’ without employing every trick in the book.
• An undocumented method is not assigned a bad grade, because there is nothing to evaluate and maybe it was left undocumented intentionally.

Distribution instead of overall grade

At the end of the “report”, Inch gives you an overview. It does so by showing the distribution of grades (including the important ‘U’ grade):

This gives you a lot more insight than an overall grade could. In the example above, I would’ve probably scored an overall ‘A’ if we don’t count undocumented objects or a weak ‘C’ otherwise.

But neither of these would paint an accurate picture. In contrast, the grade distribution tells me two things:

• There is a significant amount of undocumented code.
• But: the present documentation seems good.

Inch tells me so without judging. Maybe I can live with this amount of documentation, maybe not. In the latter case, Inch suggests to which code parts and files I should pay more attention. This way, it is perfectly reasonable to leave parts of my codebase undocumented.

No rules, no regrets

What would be the alternative? The tool could tell me

coverage: 32.9%  94 ouf of 140 checks failed

and send me on a walk of shame. But Inch does not do that.

It does not tell me to document all my methods. Neither does it tell me not to. It does not impose rules, does not expect a method’s documentation to be “a single line under 80 characters not ending in a period”.

Inch let’s me write my documentation the way I want. It can handle all forms of inline docs, but was built with an emphasis on YARD, RDoc and TomDoc. As of now, only Ruby code is supported.

Conclusion

Inch is still in it’s infancy, but I am exited about this early release. You can find the README on GitHub with more details.

Let me know what you think (I’m on Github and Twitter).

TL;DR Today I am releasing Inch into the wild. It is a tool to tell you where your Ruby code documentation can be improved.