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

Answer 1

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 2

There is no "golden ratio". It depends on the language and the way that you write it. The more expressive your code, the more it can be self-documenting -- and therefore the fewer comments you need. That's one advantage of fluent interfaces.

Answer 3

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 4

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 5

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 6

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.