Myths About Code Comments 580
theodp writes "Jason Baker gives his take on the biggest misconceptions about code comments: 1) Comments are free ('When you update the code that the comment references, you usually have to update the comment as well'). 2) Comments make code more readable ('by far the most pervasive myth that I've encountered'). 3) You should comment every function, method, class, and module ('documenting something that needs no documentation is universally a bad idea'). 4) Code must always be 'self documenting' ('would you rather use a one-liner that requires a 3-line comment, or a 10-liner that requires no comments?')."
Re:Over documentation is good (Score:5, Interesting)
Remember what is crystal clear to you may not be to the guy coming in to clean your mess up in a few years. ( or even yourself as you have learned more and advanced your skills, and have to go back, often with a 'wtf was i doing'.. )
I worked on the same system for 15 years. More than once I saw some code and said "what idiot wrote this!?" ... only to realize it was me, 5 years ago. Yes, that did indeed lead to me becoming a) much less prone to "clever tricks" and b) much much better at explaining what (WHY) I was doing whatever it was.
Re:Wrong on all accounts (Score:4, Interesting)
What bothers me is not so much undocumented code, but undocumented functions and/or blocks of code. Main should be well documented, and a function should have a line or two explaining its function, but unless its particularly obtuse code, I don't want/need documentation.
Re:Wrong on all accounts (Score:3, Interesting)
And therein lies the problem.
There are two major problems:
1) As much as I would like to say that documentation helps, I actually don't think it helps unless you writing an API. But even then I wonder. The real problem with documentation is that as much as we would like to keep it up to date, it does not happen. I personally would prefer modular code that works without tricks than code with comments and tricks.
2) The problem with comments is that it fails the psychological test. When I write something down it does not necessarily mean that another programmer is going to understand what I mean. The reason has to do with the words I choose and how I phrase things. Even with good wording I can't explain a complex system. For example, let's say that I had to explain some complex multi-threading code. Unless the third party had a level of knowledge as good as mine it will not matter what I write as a comment since they lack the basic threading knowledge. And this lack knowledge is a key problem in any complex system.
Thus if I had to choose between comments and simplicity I choose simplicity since one can understand simplicity.
Re:Wrong on all accounts (Score:4, Interesting)
Re:Does he think comments are pseudocode? (Score:3, Interesting)
Except that a programmer should be able to use (call) your api / public methods without having to read their
implementation. The method signature and comments should be enough.
Therefore, as well as conveying the gist of what the thing/method is and how it fits into its context,
you should also document all significant corner cases or unexpected behaviours of your object/method.
And if you change the implementation in such a way that you falsify one of those comments, without
modifying the comment, thats a fail, and renders your code library low quality in one stroke.
Re:One person's myth is another person's fact. (Score:2, Interesting)
My opinion is you're a stubborn idiot.
Allow me to explain. I'd love to see some concrete evidence that commenting is "pretty well proven" as well as a quantified "price of maintaining comment-free code" which you think is "well-known." The very existence of this post, and all of its replies, suggests differently. This has been argued on both sides since the idea of comments first came up. Sure there are commando style morons who refuse to type one comment, just like there were countless commandos who optimized by bypassing the operating system and going directly to the BIOS in the early days. There always will be.
After decades of software engineering, we moved from spaghetti coded ASM to readable C to object-oriented, class-based programming. Lessons learned early on don't necessarily apply. In fact, the higher level the language, the less documentation seems to be required. If data-hiding is always enforced, there are page after page of code which require absolutely zero comments because they are just get/set methods. The odd "setting this has side effects, which is why we do it this way" is an exception, not the rule.
The real exception is when you get into complicated event-driven models supported by objects. It's sometimes impossible to tell, looking at your single file where you need to make a change, which object uses this feature, or which event ultimately triggers this method. I've read some of that code, Java being my favorite example, and it's usually very difficult to see where something gets kicked off. Usually I solve it by making a breakpoint and checking the stack trace - but you can't require that someone reading your code have a working dev environment they can just open the code into and start debugging - it has to be understandable while being read, not executed. That stuff needs documentation - but it might be better done in external tech design type docs, not inline.
Very few programmers are of the hotshot variety - you might be misinterpreting a little. If I build a bridge and someone tears it down and builds a functionally equivalent version, I tend to take it personally. I'm no hotshot and I don't think that person should stay away from my perfect code, but it's something I created being thrown away or altered for no apparent reason. "[I]f you are not a hotshot you have no business touching [my] code" has little to do with the real world because it is rarely seen in the real world. No one gets permanent ownership of a file or block of code, and if you run your ship that way it's your own fault. Set up the environment so that's not even possible. Cross-training someone to be your backup is a relatively common thing to do, and eliminates the possibility of having that hotshot, so if he/she exists, it's management's fault for either enabling or not firing that employee.
Throwing away code because it's "not maintainable" simply due to lack of comments is laughable. Worse than laughable, it's cryable. Requiring that everything be commented so you can put a check mark in the "my team always comments their code" box makes you sound like the coder's worst nightmare. Creating work for no reason is absurd, but it allows management to claim they are understaffed and need a bigger team. That's the way management promotes itself, seems like - require a bigger team, then use that to show you can handle a bigger team, and it keeps growing because you have people 25% dedicated to commenting code. You're completely missing the point.
We have had requirements as a result of ISO 9001 and CMM qualification which were just as blind as you are, and as a result have code which does not match the comments at all. The functionality is clear based on context, but in the rush to get a feature out by a client commitment date (that is not within our control) sometimes these things get overlooked. It is far better to reserve comments for when they are needed. And if they are not needed, they should not exist. You want a theoretical team which updates comment
The flipside (Score:3, Interesting)
Re:Cliche, but true... (Score:4, Interesting)
I don't clutter my code with comments. If there's a comment, it's a really important gotcha, or something that doesn't make sense but has to be left for legacy reasons.
And I write a detailed description at the top of every file. Not just what a class does, but also why. Why some of the methods do what they do, and other places they might get used that might need to be changed.
Nothing annoys me more than...
/* Method name: Foo
Returns: int Bar
*/
public int Foo()
{
return Bar;
}
When a comment could be run through a preprocessor to turn it into the actual code, the comment is saying too much, and should be removed, simplified, or changed.
Re:Less verbose is more writeable (Score:5, Interesting)
Your example misses the point precisely because it's just as clear in one line than in eight. You obviously shouldn't break up everything into as many lines as possible.
Experience (Score:3, Interesting)
Re:One person's myth is another person's fact. (Score:4, Interesting)
I actually did one of those comments a few days ago. There wasn't a better way to do a particular piece of code, so I put the comment in "// This is ugly, but there isn't a better way to do it.". It's a note to myself and future developers not to bother trying to fix an insignificant ugly piece.
I do agree with the article, not everything needs to be commented. He misses out on "self commenting" where the code explains itself, so you don't need to explain it in an added comment. Intuitive variable names rather than $a $b $c are very helpful both in development, and for future maintaining.
Sometimes things are overcommented, like the default Apache httpd.conf. I've been known to clean up such files with "mv filename filename.orig | cat filename.orig | grep -v ^# > filename", just to shorten it down to something reasonable that can be read. If you're familiar with the Apache httpd.conf, there's no need for all those comments. But, if someone needs to reference them, they're in the httpd.conf.orig.
Re:Wrong on all accounts (Score:2, Interesting)
Re:Has No One Actually Studied This? (Score:3, Interesting)
A former employer (a very big multinational corporation) did a study that tried to correlate the number of comments in code to the number of problem reports against it.
Which seems to me to be representative of the sort of blunder very big multinational corporations seem particularly prone to. Just count the comments, never mind what the comment says. /* Stable sort in place, efficiency O(n log n) */
counts for the same as /* Oblig comment coz a dude in QA sez I has to */
Re:Has No One Actually Studied This? (Score:2, Interesting)
If not, someone really ought to do a serious study. And then start teaching people something that's actually known to work.
I'd be interested to see a study, but I'm sure it'd create more questions than answers given how hotly every side of this argument is debated. I think that writing good comments is much like writing good code, the only way you get good at it is reading, writing and re-writing lots and lots of code/comments. After a while you know what needs to be commented, the way it needs to be commented and you know what doesn't need to be commented. Writing relevant information clearly and concisely is a skill that must be learned and practiced.
Re:Kernighan (Score:3, Interesting)
So when you write really clever code when you are one of your peak points, you better be smart enough to explain it to your dumb self some time later when some thing needs to be changed (even if it isn't actually affected, you might not remember or understand anymore the reasons that it isn't affected