What about when you’re in a real world situation and you’ve just got to make a deadline? You can’t begin to refactor your code for ten times, you’ve just got to get that shit out of the door.
bool comment = false; // indicates whether this comment is required
Jeff,
If you are writing code that be consumed internally (not for public consumption), then comments can be minimal especially when you use excellent naming conventions for classes.
But when you write code others will use, it’s really nice to provide many more details with your comments. I find the example and code tags to be really nice to include in documentation I have written code for others to consume. Even though I use excellent naming conventions as well.
Reminds me of a GREAT article I saw a while ago about (funny) tips for creating unmaintainable code:
-
Choose variable names that masquerade as mathematical operators:
openParen = (slash + asterix) / equals; -
Choose variable names with irrelevant emotional connotation:
marypoppins = (superman + starship) / god;
http://mindprod.com/jgloss/unmainnaming.html
It’s really the opposite of self documenting code, it’s more like self-obfuscating code. 
Self-documenting code is completely worthless if it’s inadvertently documenting the wrong thing
Self-documenting is by definition the right thing. It may be poor code and wrong, but it is the correct documentation.
Comments rapidly become out of date with refactoring, and with fellow programmers not updating it.
// Newton Raphson method
private double SquareRootApproximation(n) {
(some other algorithm)
...
}
Writing tests before code documents the requirements by defining the inputs and outputs. No code comments required.
Also, why are you reading the code if you don’t know why or how you got there? Junping into the middle of a program without an aim is pretty pointless.
this post reminds me of the NeHe OpenGL tutorials, where every single line, including opening and closing braces are commented.
Comments in my code are just that - comments; little side notes, kind of what you’d note down next to someone else’s code if you were tring to work out what it did.
And if you hate giant comment blocks, don’t view source that’s been formatted for Doxygen.
If you’re doing Newton-Raphson, I hope you’re doing so for a reason other than demonstrating your Mighty Math Muscle. State that you’re using this algorithm, and why. State the accuracy bounds, and enforce via tests. Don’t leak implementation detail in the interface.
Jeff’s SquareRootApproximation(n, Type.NewtonRaphson) examle is bad for reasons already mentioned, it’s clunky, and depending on language+compiler might generate suboptimal code. If you’re doing N-R it’s usually because of speed concerns, so you don’t want suboptimal.
I do fully agree you shouldn’t comment every single line, though, and maintenance coders not updating comments can be a problem. But would you want a maintenance coder on your team who changes algorithm without updating comments? Chances are that coder won’t be writing proper tests, either.
As for Junping into the middle of a program without an aim is pretty pointless. - debugging other people’s code, perhaps?
It’s reassuring to read the replies and find that so many people don’t buy the less comments are good nonsense.
There are two main reasons that lead to this incorrect thinking:
- Developers think that code tells you what is being done and comments should tell you why it’s being done. This is nonsense. Code tells you how something is being done, and comments should tell you what is being done on a semantically richer level than instructions intended for a machine. Even better if they also tell you the why.
- Developers regularly overestimate the self-explanatory power of code they have written themselves. It’s only experience that teaches them to take nothing for granted. Please don’t tell inexperienced programmers that comments should be avoided.
I agree, however, that writing good comments requires good writing skills that many coders do not possess. Again, it doesn’t help to reassure these that comment-free code is good, because without practice, they never gain the necessary skills. In my opinion, comments and code intimately belong together and should be improved together.
By the way, I think that programming skills correspond with writing skills on a very general level. Bad writers confuse ideas, present them incoherently, get character traits wrong, use inconsistent naming, grammar and punctuation, and tell their stories in an unimaginative, boring and sloppy way, not detecting mistakes and limiting story development through these errors. Bad coders confuse and misunderstand requirements, structure code incoherently, get abstraction levels and data structures wrong, use inconsistent naming, idioms and punctuation, and sloppily implement algorithms that are unimaginative, inefficient and buggy, limiting maintenance and enhancement possibilities. I believe that good programmers are mostly good writers and vice versa. As a corollary: Most software is buggy, inefficient and hard to maintain because their authors suck at writing.
You could go a long way in telling people how to write and code correctly, Jeff, and improve their coding abilities. For my part I’d look forward to again read an inspiring post from you. It’s about time.
Apprentice: either writes comments, lots of comments or writes incomprehensible code with no comments.
Journeyman: writes self-documenting code with no comments.
Master: Writes comprehensible code that is commented where doing so enhances understanding.
Something like that?
1 Like
Do I really need to write a post saying comments are good, please use them? That’s like writing code is good, please write it.
http://www.codinghorror.com/blog/archives/000878.html
If the best code is no code, what is the best comment?
+1
Couldn’t agree more about the thrust: comments should be used sparely, and code should document when at all possible.
But let’s face it – anyone replying to this post is part of the 5% of programmers who actually give some thought to the topic while working.
It’s the other 95% that’s the problem.
What the hell???
Instead of adding a single line of comment, you recommend writing the stuff as a function/method, and comment it by giving this function a speaking name - even though the code is onl run once, and no function is necessary(otherwise it would be there anyway)?!
Sorry, that’s not real affective, and will, for all those morons that make other developer’s day hard by not being able to give functions a decent name, not make anything better.
And then the You should always write your code as if comments didn’t exist…
Totally mislead - as when you’re walking along the equator to find th north pole (not as wrong a s on the south pole, but here, not even the temperature is right…)
I code by writing the comments first - saying in human language, what I’m actually about to do, and, by that way, realizing problems in things because I have problems to describe them - so, before the first line of actual code is written, I realize problems in my spec(if such thing ever exists - in real life you don’t get these so easily).
When I write unit tests, the first thing I do is try to write prerequisites and expectations into the comment above the code - before starting to write the test. As with the coding itself, it makes me reassure, that I have enough inside in the problem to be solved so I can describe it in a short sentence - if I’m lacking this, I will never be able to write a decent line of code doing these things.
Even though I don’t want to force that style of working to others, I feel it’s working great for me - it leads to well thought out coding, and can never lead to undocumented code.
However others work - what you describe and recommend here is nothing else to me but the title of this website…
The solution, of course, is to use the Commentator:
http://www.cenqua.com/commentator/
Oops, wrong URL - get me here: http://lazyb0y.blogspot.com
I guess we all tend to fall into the overstated tone of Jeff’s articles, but like those of Joel, that’s what makes them so enjoyable and we just can’t help reacting.
I think the overuse of comments if one of the ‘code smells’ described in Martin Fawler’s Refactoring: Improving the Design of Existing Code, and a more reasonable opinion would be at least to try to improve the code until most comments become useless. I personally spend a ridiculous amount of time trying to remove all boilerplate code and extracting every bit of logical blocks to new methods with explicit names, so I totally buy that coding without comment style, but only because I’m way too lazy to keep comments up-to-date, plus I think it pollutes my editor screen. But yeah, I feel guilty about that.
I suppose the level of detail in comments depends on the level of understanding by the people looking at the code; where I work, not all ‘programmer’ are at the same level (I wouldn’t even consider some of them programmers at all) so whenever I loop through an array I have to write down what’s happening otherwise I get people ringin me up asking me what’s going on.
Jeff,
I couldn’t agree with you more. In fact, I wrote a very similar post 7 days ago about the exact same thing (shameless plug: http://houseofbilz.com/2008/06/comments.html). I think my language was a bit stronger against comments, but your language was clearly more articulate.
Jeff,
Do I really need to write a post saying comments are good, please use them? That’s like writing code is good, please write it.
No. Make people reflect. Let them benefit from your experience. Show them the how, not the what, and let them draw the conclusions on their own. Put things into perspective, rather than advocating one side. You’ve got an audience, so you’ve got responsibility.
If the best code is no code, what is the best comment?
Well, if the best code is no code, then the best job is no job. Ex falso quodlibet 
Sure, I agree that less is (sometimes) more. But you also know that there’s a limit to quality by reduction. Why shouldn’t the same be true for comments?
you are a shameless flame-baiter
Another excellent compromise that you skipped, is meaningful variable names! I am not familiar with Newton’s Method (might have seen it in school, coughcough years ago), but it looks like r is the root and t is a tolerance. Why not call them that? while ( abs( root - (n/root) ) tolerance ) would have been clear enough that I could figure out at a glance what that was trying to achieve.