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

Answer 1

Whoever has to fix code from another programmer will say as many comments as possible. The big problem with old code is: "You see what the code does. You see that this is the problem. But you does not know why the programmer wrote it like this."

To understand a bug you need to know:

• what should the code do (not what the code does) and why.
• The contract of every function. For example if there is a NullPointerException then where is the bug? In the function or in the calling function?
• On every Hack is to described how the problem can be reproduced (Language version, OS, OS version). For example we have many hacks for an old Java VM that isn't supported anymore. But we are not sure if we can remove it because we don't know how to reproduce them.

We have a ratio of 2-3%, which is too few. I think that 10% is good for large or long lived projects.

Answer 2

I try to keep comments at a minimum. Code should be self explainetory and while source code tends to change the comments almost always remain behind as a wrong explaination.

Answer 3

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 4

My rule is this: if there is something that needs to be said and the code can not be made to express it, then you may write a comment. Otherwise, if the code can express the idea, then you must express the idea in the code or its tests.

If you follow this rule, then your code should only need comments when it is dealing with some inobvious problem in the hardware or operating system, or when the most obvious algorithm is not the best choice. These are "this is weird because" comments, and really are just a coping mechanism.Most of the time comments in the code are really just apologies for not writing it in a more obvious way, and such comments should be obviated and then deleted.

Even the good comments often become lies over time, so information in non-executable, non-testable places like comments are to be eyed with suspicion. Again, the answer is to first obviate the comment, then delete it.

My ideal ratio is zero. However, the world is less than ideal, so I accept comments when there is no other way to communicate an important idea.

Answer 5

I have a very simple rule-of-thumb: If you need to stop and think more than ~15 seconds when coding some piece of code (say, a function or complex loop, etc.), then that piece of code needs a comment.

It works really good for me. Next time you, or someone at your level of understanding of the overall codebase, runs into that piece of code, (s)he will immediately see why was it done the way it's done.

Answer 6

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. :)