What's the golden code/comment ratio? [closed]

Question

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 2 years ago.

Is there a code/comment ratio that you consider to be a sign of good (bad) code health?

Can you give examples of open source projects that are considered to be well coded and their respective comment ratio?

(I realize that no ratio is "true" for every project and there may very well be crappy projects that exhibit this theoretical golden ratio. Still...)

Answer 1

LOC / LOcomment = yearsofexp / 5

Answer 2

The golden code/comment ratio is the intersection of

• comments needed to remind yourself of things you had in mind while coding
• comments needed to remind others of things you had in mind while coding
• comments your customer is willing to pay for (because good comments cost time)
• the developer's interest in producing obfuscated code because of job safety (if he or she is working for a company where a developer can get away with it)

This also shows why that ratio is different for every project and every team.

Answer 3

If you want some real world data on comment ratios for different languages, take a look at Ohloh.

As an example, you can look at the various metrics for the Linux Kernel source.

Answer 4

Comments should be very rare and valuable, almost always expressing the "why" and never the "how" (the exception being when the how is complex and not easily discernible from the code).

Every comment is a hint that you may need to refactor to make the code's intent clearer. Every comment risks becoming out of date as soon as it's written.

We have almost no comments aside from XML comments in our xUnit.net project, but some people seem to find the code clear and easy to read. :)

Answer 5

I think everyone can agree that 0 comments can generally be considered sub-documented code. Remember that even the most self documenting code can only ever document what's there; never what was intentionally left out, optimized away, tried and discarded, etc. You'll always have some need for English, basically, in your source files, or you're bound to leave out important caveats and design decisions.

I'm interested in how these sound principals you guys are advocating (with which I'm in full agreement so far) translate into code statistics. In particular, what open source projects are considered to be well (not over-) documented, and what's the comment ratio there.

Answer 6

There is no "golden ratio". It depends on the language and the way that you write it. The more expressive your code, the more it can be self-documenting -- and therefore the fewer comments you need. That's one advantage of fluent interfaces.