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

Answer 1

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 2

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 3

I comment everything I think is ambiguous, or should be explained. Often, I over comment. Why? Because you never know who will work on your code. I like to imagine a situation where they replace half the team with monkeys who only understand that when they press enter on a line, they get a banana. So, if they at least learn to read, they won't change my logic without reading the comments first.

Case and point:

// Delete the helloworld file
exec("rm -f helloworld.txt")

Won't get changed to:

exec("rm -rf /")

Unlikely, I know, but even some good developers are known to change logic because it doesn't look right and not because there was a bug, or requirement change.

Answer 4

You can't mandate a fixed code/comments ratio otherwise you finish up with code laced with noise like:

// Add one to i
i++;

which just clouds the code.

Instead look at the complexity of the code and see what you need to explain, i.e. squirelly logic, why certain magic numbers are used, what assumptions are present regarding incoming formats, etc.

Switch on your maintainers mindset and think what would you like to see described regarding the code you've just written.

HTH.

cheers,

Rob

Answer 5

It can vary quite a bit. For example, you can have code so well written that comments would just be a waste of time.

You need enough comments so months later you can look at your code, read the comment, and just pick up where you left off, without much effort. If the life story of the code isn't required, don't write it.

Answer 6

Comments don't just explain the code - they also guide the debugger who is looking for the piece of code that does something.

Retrieving a customer's order history or calculating whether an enemy player is visible may take dozens of lines of code, and even an expert programmer may take several minutes to be sure that's what it does. A comment that says "retrieve the customer's order history" allows the debugger to not investigate that code at all, if he knows that the order history isn't the problem.