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

I have to say I came here looking for an answer around 2 of comments per 1 line of code. Even if this is an exaggeration it's in the right direction! Instead I see people recommending treating comments like truffles or other rare commodity. Looking from a peculiar perspective of academia, were code quality is low and use of version control is even rarer then truffles I would urge anyone to write as much comments as possible, even against your own judgement of whether the comment is 100% necessary.

Comments make your life easier because chances are you are going to be thinking, what the hell was I thinking when writing this!

Answer 2

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 3

Comments have 3 uses, IMO:

• Explain why the code does what it does
• Document the interface for a module
• Explain why other approaches to a chunk of logic weren't taken

If the code is doing something basic enough that the why is clear, which should be most of the time in most domains, then the comments within the logic should be minimal... even approaching none. Comments should never be explaining the what (with possible exceptions to say, for example, that the function is an implementation of the Foo Algorithm as explained in Bar Publication). If you need to explain what you're doing, you're doing it poorly.

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

There is an excellent discussion of code comments in Steve McConnells () book Code Complete ( I have the first edition but I believe is now a second edition link text)

In summary it reinforces what the other answers stated - should be rare and describe the why not the how - if you can refactor variable and method names to replace comments then that should be prefferred - with most IDE's offering some kind of intellisense (or as I once heard Don Box describe it as - intellicrack due to its adictivness) there is no reason to truncate variable/method names when a longer clearer version would communicate its intent more clearly

Answer 6

I don't suppose anyone can give you figures, but it should be far higher in header files than in source.

I'd expect the header file for a class to document all the classes/functions/etc publicly accessable by including that header file. That can be quite a lot of lines to document a function whose prototype is a single line (no, just choosing good names for functions and their parameters isn't enough - it can be, but often isn't). Three lines of comment for every line of code would not be excessive.

For actual code, it would be much lower. I don't agree with the extremists who think you should aim for zero comments, but certainly if you think you need comments you should first consider whether the code could be made clearer.