Why Inch doesn't use percentages

Inch is a documentation measurement tool for Ruby that gives you grades instead of a “coverage score”. In this post I will explain the reasoning behind this.

Coverage is not for everybody

As Piotr Solnica explains right at the beginning of his post Common Pitfalls Of Code Metrics, metrics and metric tools can be both helpful and harmful. If you always aim for 100% in each tool, you basically start judging your code based on its cover. This is why Inch tries a more relaxed approach based on grades rather than scores.

Grades have their own problems, scientifically speaking, but for the task at hand - giving a general understanding of how well some part of code is documented - I think they provide a lot more flexibility than raw percentages can.

You can get an A without employing every trick in the book. If you get an A in Inch, it means the docs seem really good. It does not mean the tool ticked all boxes on a given checklist. And if you get a B, it still means the code seems properly documented (read: the documentation is seriously good enough in most cases).

Not everything is about numbers

Getting an A or B is a lot more satisfying than getting 85% or 75%, especially on parts of your code you care about, because you don’t get the feeling that you missed something. It also prevents you from adding stuff just for the sake of reaching a highscore. There is no rule in Inch that says “every class needs a code example” or “every method should somehow specify its return type” (although it helps during evaluation).

Last but not least: if you have undocumented code, Inch gives you the special U grade, because the absence of documentation might be intentional and should not lead to a bad evaluation.

Conclusion

At the end of the day you have to decide which parts of your code you want to document and how extensively you do that. Inch can help you doing this in a non-pedantic way.

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

TL;DR Inch is a tool to tell you where your Ruby code documentation can be improved (without being snobby about it).