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...)
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.
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
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.
There is no such thing as a good comment to code ratio. In the old days some people believed that you needed to have a comment at the head of every function explaining what it does.
However, with the advent of modern languages code is pretty much self documenting. This means that the only reasons left to put a comment in the code is to either explain where an oddball decision came from or to help with understanding a really complicated subject.
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. :)
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
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.
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.
I think everyone can agree that 0 comments can generally be considered sub-documented code. Remember that even the most self documenting code can only ever document what's there; never what was intentionally left out, optimized away, tried and discarded, etc. You'll always have some need for English, basically, in your source files, or you're bound to leave out important caveats and design decisions.
I'm interested in how these sound principals you guys are advocating (with which I'm in full agreement so far) translate into code statistics. In particular, what open source projects are considered to be well (not over-) documented, and what's the comment ratio there.
The golden code/comment ratio is the intersection of
This also shows why that ratio is different for every project and every team.
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.
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
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.
Comments have 3 uses, IMO:
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.
All comments, no code. Like a novel.
And a nice cup of tea, with some cakes.
Code is too much like work, much better to just have a nice chat.
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
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?
Where ever has to fix code from other programmer will say so much as possible comments. The large problem is for example with 10 years old code is: "You see what the code do. You see that this is the problem. But you does not know why the programmer has write it such"
To understand a bug you need to know:
We have a ratio of 2-3% and it is to few. That I think 10% can be good for large projects or long living projects.
If you want some real world data on comment ratios for different languages, take a look at Ohloh.
As an example, you can look at the various metrics for the Linux Kernel source.
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.
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.
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.
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.
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.