Slashdot Mirror
Myths About Code Comments
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?')."
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.
I work for the Department of Redundancy Department.
If you're writing in C, do yourself a favour and check out this editor: http://www.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.)
If you're a zombie and you know it, bite your friend!
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.
If your comments are that detailed, you're doing it wrong.
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.
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.
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."
My other car is a 1984 Nark Avenger.
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.
I dont read
Which is why every compiler for the last 20 years has done it where appropriate. Hell, even the toy compiler I wrote as undergraduate coursework did that transform. All that you achieve by doing it in your code is making your code less readable (and slower on a few architectures and in a few circumstances on others).
I am TheRaven on Soylent News
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.
Sounds sorta like literate programming.
You do realize that some of those types of comments aren't really intended for humans anyway, but more for documentation generators like javadoc and doc++ ?
Shifting is no longer considered superior to multiplication on x86 because shifting has flag dependencies that multiplication does not have. The P3 was the last processor to favor shifting over multiplication (actually.. not sure about the Atom)
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.
"His name was James Damore."