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?')."
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.
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.
It's surprising to me that someone has submitted this as a "news" item. News flash! Everything you know is wrong. Sorry I don't buy that. If you don't comment your code, I won't pay you for it. I'll inform the management that you neglected an important step and don't deserve a good reference. I won't be able to give you the benefit of the doubt when your code doesn't make perfect sense. I'll trash talk your code in front of your colleagues. Look at all the mistakes in this guy's work; I'll sure never recommend him if his resume crosses my desk. We may need to just rewrite this stuff because it's not maintainable as written.
What's really annoying is when they put comments that don't elucidate the code or their intent; they're just snide little messages from one know-it-all to another. They're too embarrassed to actually explain the code because that implies a level of insecurity they would rather not admit to. So instead they say things like: /* yeah, I don't like this either */
or
# hack, to be fixed later
Wooooo, really helpful comments there. I've seen this sort of thing countless times in my career and most others I know have as well.
it's = "it is"; its = possessive. E.g., it's flapping its wings.
No Comment
Clean code tells you how, good comments tell you why.
Fixing the "how" becomes significantly easier when you know "why" the code was there in the first place.
That green slime had it coming.
Having worked as a programmer for many years, all I can say is poorly commented and undocumented code is unprofessional and I would rather
rewrite it than try to decipher it. I've heard all of these excuses before and all I can say to the people that make them is: Your code is not as
good as you think it is.
The difference between Canada and the USA is that in Canada healthcare is a right and gun ownership is a privilege.
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.
Stupidity... has a habit of getting its way.
Christ, I know everyone has their own personal style and everything, but this is just pernicious. In any case, the author gives the game away: when he thinks code is overcommented, he can ask Emacs to hide the comments. So far as I know there's no automatic system that will generate the comments that the author failed to put in because the code was "self-documenting". This is particularly important when you're working with anything other than standard libraries --- you might know what "libfzp_inc_param_count_fast", but your reader probably won't.
Right now I'm working on a crypto library that incorporates a lot of very specific elliptic curve operations. My technique is to comment the hell out of every damned interesting piece of code on the assumption that a picky reader can turn off the damned comments if they get in his way. In fact, there are various places where I've actually scaffolded all of the comments before writing a line of code. Doing otherwise would have been an enormous headache and made bugs a whole lot more likely. And this way even a non-expert should be able to understand the entire program flow.
Unfortunately, one of the previous pieces of software in this area followed the poster's "self documenting code" style (very nice, clean, well written code with no comments), and even I find it difficult to piece together what's going on in places --- not because all of the code is crypto-specific, but because the author has thrown so much effort into writing "clean, pretty" code that it's actually hard to know where the crucial pieces are. I can't quite explain why I find this so irritating, but perhaps some of you will know what I mean.
No offence intended to him, but he's just re-interating the sort of commentary on commenting that's in Code Complete, The Practice of Programming, Linux kernel CodingStyle etc. He's not offering any original insights, or telling war stories that people can learn from. Any decent programmer would already know these myths, and if they didn't, they really should be reading books such as the ones I've listed, not a blog entry with very little original content.
IOW, what makes special enough to be Slashdot front page news?
The Internet's nature is peer to peer - 20050301_cs_profs.pdf
Every line should be commented, like: // Declare function called doit with one int param that returns an int // See above comment // The function's open brace. I like to put braces on their own line. You should too!! BTW, this is C code, so braces are totally the way to go. // Check if i is 0. You know, in C, "==" is the way to compare values, unlike in VB where you use a single "=". Just thought u should know. // Return 0. That is, all the bits of the return value are 0. We could also return i, because i is 0, too. That is, all the bits of i are 0. On a 32 bit system, there would be, like, 32 0's. // Begin an if block using a brace (this is C syntax!!!) // Declare an int variable named j that is one less than i // Return the sum of i and the value of calling doit with j // Finish the if block with a C close brace. By the way, we could have written the above code as return i + doit(i - 1) without using the braces. // The function's close brace.
int doit(int i)
{
if(i == 0)
return 0;
else
{
int j = i - 1;
return i + doit(j);
}
}
There! Now that is both way readable and informative. Anything less would just not pass my code review.
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. Not surprising to me, they found that in general the more comments in the code, the more problems were reported against it. That was my observation as well; bad programmers couldn't figure out a straightforward solution to a problem so they wrote messy code with lots of comments trying to explain what they were doing. The really good programmers wrote simple clean code that only needed a few comments.
Another characteristic of bad programmers that I noticed was their tendency to keep copying data from one data structure to another instead of using it in place. Obviously an indication of bad design, and it introduced lots of bugs. You knew as soon as you opened a source file and saw comments like "Copy blah-blah data from abc array to xyz array" that you were in trouble.