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.
I do think good commenting has to be a key part of software engineering (when it finally becomes a real engineering discipline), and I know software engineering is a hot topic these days, so perhaps there's a paper on this that I just haven't seen yet. If not, someone really ought to do a serious study. And then start teaching people something that's actually known to work.
--Greg
I disagree with this general statement:
First, I think any time you consider writing some clever one-liner in real production code you should rethink long and hard. Is the hypothetical 6 fewer lines of code really worth it? Unless you're doing it for absolutely required performance reasons, the 6 lines of code you save won't buy you anything but the wrath of whoever has to come along in 3 years and refactor your code.
Of course you can be too verbose, but it's a much rarer problem than the alternative. Even overly verbose code is usually easier to understand, easier to maintain, and easier to refactor than that clever little one-liner. And if you're that worried about a verbose section of code, extract a method, give it a good name, and be done. Now you have both a one-liner method call that is easy to read in context and a more verbose implementation that is easier to understand and maintain in the future.
"What do you despise? By this are you truly known." --Princess Irulan, Manual of Muad'Dib
/)
In other news, people have personal preferences, just as they do in the literary world. Some people like Ayn Rand, others hate her. Some like Stephen King, others hate him. Not so much their stories, but their writing styles.
Snowcrash is an awesome story; one many can appreciate, but most people couldn't get through his writing style to finish the book.
I think that if more people wrote code (or, for that matter, books) like George Orwell wrote his books, code (and books) would be generally more readable: shorter sentences (lines of code) which convey a single meaning (function), strung together into short paragraphs (code blocks), chained together into a larger cohesive whole.
~/ssh slashdot.org ssh: connect to host slashdot.org port 22: too many beers
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.
If your comments are that detailed, you're doing it wrong.
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
Easy. 10 lines, no comments. After writing a couple of million lines of code, the more code I write, the more I unwind it. Somewhere along the line, adolescent programmers got the idea that jamming all your logic into as few unreadable lines as possible is the fastest way to manliness. Way, way wrong.
Modern compilers and interpreters do a pretty good job nowadays. Source code bytes are near free. If you have to skull out dense code 6 months after you've written it, you're doing something wrong.
(OK, Lisp and APL are special cases, but really, when's the last time you wrote Lisp or APL, other than for fun?)
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.
If you don't header-comment your class or public method,
I have to conclude that you cannot articulate what it is or what it
means or is for. So probably the code is incoherent/inconsistent too.
So that's going to make me write my own instead of using your code.
Or maybe you can articulate what it is about but are borderline
autistic and don't see the need to communicate meaning to others.
To me this just means you are so inexperienced in programming that
you a) don't understand the costs of maintenance, and
b) don't even realize that you yourself aren't going to be able to figure
out your code in six months.
Either way, I'm not using that code if I can help it.
Where are we going and why are we in a handbasket?
Early COBOL and Fortran computation code proves you wrong here. COBOL, without COMPUTE, required a separate line for each operation. Fortran from the start showed simple algebraic equations.
COBOL
======
MULTIPLY B BY B GIVING B-SQUARED.
MULTIPLY A BY C GIVING A-C.
MULTIPLY A-C BY 4 GIVING A-C-4.
MULTIPLY A BY 2 GIVING A-2.
SUBTRACT A-C-4 FROM B-SQUARED GIVING DISCR.
CALL SQRT USING DISCR GIVING RT-DISCR.
SUBTRACT B FROM RT-DISCR.
DIVIDE RT-DISCR BY A-2 GIVING ROOT-1.
Fortran
=====
R1 = (-B + SQRT(B**2 - 4*A*C))/(2*A)
Do you want 8 lines of code to write out the quadradic formula? Is that any clearer than one line? A simple one-line comment explains what *root-1* means to the program as a whole.
I've seen people write out intermediate variables like that using PHP or Python. Both languages handle that for you.
The code which is business critical and necessarily complex gets commented a lot as a mitigation measure. But it still has problems, often because the business requirements change a lot or are poorly defined.
http://michaelsmith.id.au
Working in accountancy (and doubly-so for audit) a well-commented file is absolutely necessary. Like (I suspect) computer code, the file should stand on it's own - a competent fellow professional should be able to fully understand it and be comfortable reaching the same conclusions. This is not only good practice for the benefit of your firm but a professional requirement: my institute comes along every few years, selects a few files and basically if they have difficulty understanding the file (or worse, reached different conclusions) then you're in a lot of trouble.
Many of the points in TFA hold up well however - explaining things unnecessarily merely adds bloat, irritates and wastes the time of the reader by telling them obvious, patronising or pointless things. And yes, a perfect accounts job doesn't require any explanation because the schedules will be self-explanatory.
The thing is though, if you're doing anything complex (earning your salary), have to make corrections (hackjobs) or judgements then you need explanations. Manager's will be reviewing your work and you or a colleague will be referring to it next year. If explanations go out of date, update them - if they had value before then value is there in updating them. Yes there is a cost, so there is a tradeoff vs their value to the file. The key is competent fellow professional. Assume your colleague will be reviewing your work and be satisfied that they will be able to understand and appreciate it.
If you're just churning out "stuff that works" then you're at best a technician.
Indeed.
Sometimes there is a very good reason for including clever, non-intuitive code in a project. But that clever code needs to be very well documented because the next guy to touch it may not be that clever.
When in doubt, optimize code for future maintainability and legibility. Hardware gets faster. Programmers don't.
DG
Want to learn about race cars? Read my Book
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.
While you are right (as all *experienced* programmers know, anyway) that /* increment the counter */ comments are pointless (but harmless) you've missed an extremely significant type of comments. These are the warning to future programmers why you DIDN'T use the obvious approach, or why a particular algorithm is not suitable for the task in question. Further, code that has been corrected, modified or had bugs fixed MUST have comments to identify that fact. These comments are at least as valuable as the actual code. Again, experience will teach you this.
Finally, never, ever forget the most important rule of commenting. NEVER include a URL in a comment. They change over time and cannot be relied upon to still exist in 3 months, let alone the lifetime of a software product. A similar warning should exist for book / magazine references, too. Not only do they become unobtainable or go out of print, they also get modified or corrected in the "second edition" and therefore still can't be relied on. If an algorithm has a well known name, such as Bresenham's, then by all means quote that otherwise, explain the algorithm in, or before the code that implements it. Unless you want the next guy to curse your name - provided you put that in the comments.
politicians are like babies' nappies: they should both be changed regularly and for the same reasons
- 6000 lines of Pascal
- 200 global variables
- 3 local variables
- 1 comment - the single word "midlertidig"
Oh, and one bug. Code really was less buggy back then.
Now get off my lawn, you kids.
I can't count the number of times I've written a very carefully researched small handful of lines of code that are either not intuitively obvious, or would leave more questions than they answered when read. When I've spent days demonstrating through thorough measurement that, for example, a certain constant requires a specific value, that fact gets documented with potentially many paragraphs of comments. Not doing so would be irresponsible, and a waste of my time when I tried to understand, months or years hence, why I had written that small handful of lines.
To quote one of the Ramones who was criticized in an interview for writing songs with only three chords, "yeah, but they're the RIGHT three chords." With music you can feel if the chords are right. With code, sometimes you have to document.
Put my fist through my alarm clock with its ding-dong death inside my ear. - The Blackjacks.
Citations:
http://desktoppub.about.com/cs/finetypography/ht/line_length.htm
http://desktoppub.about.com/library/nosearch/bl-linelength.htm
Notice how newspapers break the content into columns, even if a single article covers 5 columns in page width? There is an optimal text width that helps people read best. 80 might be a number coming from punch card days, but it is still a good approximation of "ideal" column width as used by various publishing standards. It is, in fact, a bit more than ideal column width. I see 2 reasons for this:
1. Breaking simple text simply results in excessive hyphenation. Breaking code into multiple lines has higher impact because code has its own indentation too.
2. Indented code that starts at 20th column and ends in 80th column => total width is 60 columns which closer to the ideal columns width.
Bingo Dictionary - Pragmatist, n. A myopic idealist.