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:One person's myth is another person's fact. (Score:5, Informative)
I find the most important comments are those that tell you WHY something was done the way it was. I do this with my own code when I track down and fix a bug that turns out to be caused by some very subtle effect or easily made mistake. I put the comment there to stop myself (or someone else) from "fixing" / "cleaning it up" later because they don't realize why it's done the way it is. Comments like:
# yes, 1, not 0. If all four of the lists are allowed to go to 0, we will blow up later with DBZ.
And having a sometimes very poor memory of code written long ago, this saves me from myself more than others.
Re:Wrong on all accounts (Score:2, Informative)
I would rather
rewrite it than try to decipher it.
In the environment I work somebody will try to import your change later and they will want to know why you made that change. They aren't going to be very impressed if your answer is that you couldn't understand the original code. By making that change you would be creating work for a lot of other people down the chain.
Re:One person's myth is another person's fact. (Score:2, Informative)
If you're writing in C, do yourself a favour and check out this editor: http://www.geany.org/ [geany.org]
It's the slickest C editor that I've ever had the pleasure of using. It seems little-known, though, and I don't know why.
(It handles other stuff than C too, but I haven't used it for any of those yet.)
Re:Wrong on all accounts (Score:5, Informative)
Wrong on all accounts
RTFA, the article starts out with these two sentences:
It seems to me getting good at writing comments is an under-appreciated part of a Programmer's development. However, I feel that this is a part of programming that's almost as important as writing code itself.
His point is that worthless comments are worse than no comments at all. Unfortunately a large percentage of the comments you see in code today were autogenerated by the IDE and are just noise.
Does he think comments are pseudocode? (Score:5, Informative)
If your comments are that detailed, you're doing it wrong.
Re:One person's myth is another person's fact. (Score:1, Informative)
Well, everyone's welcome to their opinion, but it's pretty well proven after decades of software engineering that code should be commented. The price of maintaining comment-free code is well known.
The frilly article said nothing about not commenting code. It is against silly comments.
There is a school of thought among programmers who consider themselves hotshots that if you are not a hotshot you have no business touching their code. The problem with this attitude is that it has little to do with the real world, where people change jobs and programmers inherit someone else's code. If you want to write perfect, comment free code in your perfect little world, go right ahead, but don't expect to make a living at it most of the time.
I don't want to write comment free code, but I also realize that extensive commenting is stupid and counterproductive. I have seen too many instances of code, where nearly every line of code is commented and most of those comments add absolutely nothing of value -- on the contrary, the comments just make the code more difficult to read and add to the burden of maintenance.
I have also seen too much "if-then-else-switch-for-break-continue" code, where the extensive commenting is a symptom of absolutely awful code. Fix the code and you can at the same time get rid of most of those comments, while still leaving the code more readable than it was before. Generally, if you need more than three levels of indentation, you should really consider for a moment if you could structure the code better. The same thing with ifs, switches and other control structures; if you have a 30 line mess of control structures, you're quite likely doing something wrong and instead of adding to the mess by writing another 30 lines of comments, you should think about ways to make the code simpler (something that might be understandable with a short single comment).
Some people have a stupid notion that the more comments you write the better, but that is simply wrong. Over-extensive commenting can be almost as bad as not commenting at all, because it bloats the code base (more to maintain, since comments must be maintained as well!), makes the code less readable and because it drowns out the really important comments. The important things to comment are functions (especially if you want to generate API doc from the code), loops that aren't obvious (commenting invariants if often a good way to do this), and constraints and gotchas (ie. if there's some API/platform/algorithm imposed limitation or requirement, don't expect the people reading the code to know about it, but tell exactly where the limitation or requirement comes from and what it is!). When you're using some commonly used algorithm, it's also good to mention it, since it really helps "getting into" the code, if you know what to expect.
Commenting "why" (Score:2, Informative)
I've heard one person after another argue about how to comment and how much to comment, but what I've never seen is any kind of serious study attempting to measure what actually works best.
FWIW, in studies of the problems developers encounter in practice, one recurring difficulty is working out the motivation behind a given piece of code. This supports advice to comment why the code is written the way it is. See, for example:
Both papers were coauthored by Robert DeLine and Gina Venolia of Microsoft Research.
In LaToza, 66% agreed that "understanding the rationale behind a piece of code" was a serious problem for them.
In Ko, "Why was the code implemented this way?" was the second most frequently unsatisfied information need among the developers observed.
Re:Cliche, but true... (Score:3, Informative)
To supplement my comment elsewhere, what you're suggesting can be more easily documented in a tech design type of document, not inline. It's easier to find that way, and you can include pretty pictures too.
Kernighan (Score:5, Informative)
It was Brian Kernighan who pointed out that:
"Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it."
Re:One person's myth is another person's fact. (Score:1, Informative)
Let the compiler do its job. It can optimize better than you can and your code will be more readable.
Re:Code format (Score:3, Informative)
An 80 column line limit is also OLD, I never edit in narrow windows >160 common.
How you edit is not important, how the team you are part of all edit is. By making lines 160 characters long you force everyone to have to code the same way you do. What is lost to you by breaking a line at 80 characters since it is much easier to scroll up and down in a document than it is to have to scroll left and right once a line.
This the single worst trait found in developers, (I know I suffer from it) a lack of consideration for being part of a team.
Re:One person's myth is another person's fact. (Score:3, Informative)
Re:One person's myth is another person's fact. (Score:2, Informative)
Unless you use a really crappy compiler, the compiler will turn a multiplication into a bit-shift for you. That is, unless you're being really clever with bit-shifts, like for example when you write a deeply optimized CRC algorithm which minimizes memory accesses and code size. Very few people write that kind of code though, because it's usually hidden in libraries. Highly optimized (and consequently highly unreadable) code must be highly reusable and should obviously be well documented.
The "comment your code" dogma is a simplification for people who don't understand that code is written for people as much as it is written for machines. The person reading your code must be able to understand it. If the code alone is clear enough, comments can be harmful (because they pose a risk of code-comment divergence, require maintenance, basically all that was mentioned in the story). The problem is that clever programmers usually have a different idea of "clear enough" than others, so they frequently misjudge the necessity of comments.
On the other hand, there is this idea that programmers need to change code which they do not fully understand, so there should be plenty comments. That is very dangerous concept which will lead to many problems. If you don't understand the code, do not change it. Too much commenting can lead to overconfidence in maintainers. Comments are human language and therefore imprecise. They provide room for misinterpretations. which in turn increases the chance that the maintainer feels confident that he's fit to change the code even though he is mistaken about the way it works, the circumstances it is used in or other aspects that he should but does not understand. Too little commenting will cause a different kind of maintainer error. If the maintainer does not see a chance of understanding a piece of code, he will either resort to trial and error (feeling confident that test-based programming will do its magic, which it won't) or rip it out completely and rewrite it, but since he doesn't understand the code, the replacement code will fall short of the requirements.
Clear code which can be understood without comments should not be commented and is really the optimal way of coding. Unfortunately it is also so rare and expensive that "comment your code" as a general rule is still a sane requirement for all levels of programmers. I'm a big fan of high-level documentation, but I rarely see a reason for in-function/in-method comments. They're usually a sign of early optimization (aka unnecessary cleverness, like writing <<1 when you mean *2), bad structure, implicit requirements and other failures which should not be handled at the code-monkey level. If you find yourself writing lots of very local comments, try to find what the actual problem is and solve that, but until you do: Keep commenting your code.
Re:Has No One Actually Studied This? (Score:2, Informative)
Sounds sorta like literate programming [literateprogramming.com].
Re:Cliche, but true... (Score:5, Informative)
Re:More verbose == less readable? (Score:1, Informative)
You'd have to document why you think all file names will fit on a single command line.
There are probably file systems where all the file names together wouldn't even fit in RAM (admittedly the whole thing might take too long to run to be reasonable then, but it sure is a tradeoff, and I think that's a good example of something that needs documentation)
Re:One person's myth is another person's fact. (Score:3, Informative)
specifically:
mul or imul always alters the entire flags register, while shl or sal only alters part of the flags register. This partial update to the flags register breaks out-of-order execution and register renaming (creating a dependency on the state of the flags register prior to the shift), among some other negative effects.
div and idiv are still dogs and should be avoided.
For awhile there it was quite difficult to get a C compiler to NOT emit shifts in place of constant multiplications, which became an optimization nightmare for those of us who cared, because the compilers were outright and utterly wrong.