Using Badges

Putting badges in READMEs

Like many services, Inch CI provides badges to be embedded in READMEs. That way, visitors and potential contributors of your GitHub projects can immediately see that you value documenting your code.

Here is an example from one of my projects:

Hopefully it's mostly green when you're reading this.

Understanding the "progress-bar"

Inch evaluates inline-docs and reports grades for each class, module and method. The badges display up to four segments, with each segment representing one of these grades:

• A Seems perfect, Inch can't make any suggestions for improvement.
• B Properly documented. Inch is able to make (pedantic) suggestions for minor improvements.
• C Something seems off here, like a mispelled parameter name. Please take a look.
• U Undocumented. This is assigned a special grade, since almost every project has parts that are not in need of explicit documentation.

The widths of the individual segments represent the distribution of the grades.

In the above example, you can see a grade distribution that tells you four things:

• There is a significant amount of documented code.
• The present documentation seems really good.
• There are some items that should be checked on.
• There are still some undocumented methods, which should not be a big deal.

This provides a lot more insight than an overall grade could and does a much better job of painting the bigger picture.