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

between 3% and 9.5%, more or less

Answer 2

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.

Answer 3

There should be comments there where you feel them necessary. Not more and not less.

Comment the parts that you feel you might not understand after 6+ weeks of break when looking again at the code

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 like to use commenting to annotate code that I make sure is easy to read and has informative variables. That being said, I like to try to write every line of code to be as informative as a comment if possible. You should be able to have a very strong gist of what the code does before you read the comments, or you're doing it wrong.

Answer 6

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.