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

0/0 ; zero divided by zero
Runtime error (func=(main), adr=3): Divide by zero

an implied "Do What I Mean" command with a "no comment" comment?

Answer 2

There is no such ratio.

Usually, Comments should only be there in situations where something might be genuinely unclear, like

// Do not Dispose!
SPSite site = properties.Feature.Parent as SPSite;

On the other hand, if you are selling Code to someone, it will need as many comments as possible. Imaging selling a 3D Engine or some other Games Middleware that has no comments. Sure, API-Documentation etc. are a big part of such Middleware as well, but good commented code pays off as well. Stuff like "Add 1 to i" is still too spammy, but something like "CreateDevice() will first check if DirectX 10 is available and fall back to the DirectX 9 device if not", can be really helpful, even if it's trivial to see from the code.

Generally, Internal Code is usually a lot less commented than code you sell, but exceptions may apply.

Answer 3

Sorry, there is not rule of thumb. Frameworks and libraries, per instance, requires much more comments because programmers will be customers and haven't time to read code every time they need to invoke a method.

Projects where you are writing/reading code needs less comments and should try to improve code readability instead of comment/code ratio.

Kind Regards

Answer 4

There is no golden ratio. The number of comments depends greatly on the inherent complexity of the code. If you're just writing CRUD applications, you probably don't need a lot of comments. If you're writing an operating system or an RDBMS, you probably will need to comment more, as you will be doing more complicated coding, and will need to make it a little more explicit why you are doing the things you are doing.

Answer 5

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 6

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.