Comments are More Important than Code 1021
CowboyRobot writes "I was going through some code from 2002, frustrated at the lack of comments, cursing the moron who put this spaghetti together, only to realize later that I was the moron who had written it.
An essay titled Comments Are More Important Than Code goes through the arguments that seem obvious only in hindsight - that 'self-documenting' code is good but not enough, that we should be able to write code based on good documentation, not the other way around, and that the thing that separates human-written code from computer-generated code is that our stuff is readable to future programmers.
But I go through this argument with my colleagues, who say that using short, descriptive variable names 'should' be enough as long as the code is well-organized.
Who's right?"
Raskin (Score:5, Informative)
For those who don't know (which apparently includes whoever is in charge of the linked article), Jef Raskin passed away this february. You can view the official press release, [raskincenter.org] or read more about [wikipedia.org] his contributions to computer science. I don't know when the article was written, but it seems it should mention that Raskin has passed away. In any case, his advice about commenting is good, just as his advice on user-interface design has always been lucid and helpful.
It is not math, it is not universally readable (Score:3, Informative)
If it turns out that after all that, our code still isn't intelligible, then isn't this some monumental failure of C, Java, BASIC and the rest, whose whole raison d'etre is to make weird things make sense?
This is not algebra in high school where you lose points for not showing your work. This is the real world where an application might have 100's of lines of codes, maybe 1000's. It might be a bunch of classes in java working together. And then there is the logic, the work flow.
Plus, many companies use peer review for raises and advancement. If your peers have a hard time understanding your code, it will hurt you later.
Most people today don't work 30 years for one company. That means someone else will get stuck with your code.
Now either you will give that person months to go through all the code, to try and figure out how it works, or you will have code with comments that will help him hit the ground running.
Re:Not necessarily comments... (Score:1, Informative)
The main idea is to regard a program as a communication to human beings rather than as a set of instructions to a computer. Your program is also viewed as a hypertext document, rather like the World Wide Web. (Indeed, Knuth used the word WEB for this purpose long before CERN grabbed it!)
CWEB is a version of WEB for documenting C, C++, and Java programs. WEB was adapted to C by Silvio Levy in 1987, and since then both Knuth and Levy have revised and enhanced the system in many ways, notably to support C++ and ANSI C. Thus CWEB combines TeX with today's most widely used professional programming languages.
look it up people...
Comments Should Reflect Intent (Score:5, Informative)
The above would be far more useful like this:Now the intent of the method is clear, and anyone coming along who wonders why it's hard coded will know under what circumstances they should change it to a formula (namely, if MyClass becomes capable of meeting the Magilla criteria).
Comments can be good, but they should always be a guidepost to the intent of a block of code, and not attempt to explain how the code achieves that goal.
Re:Use long variable names (Score:1, Informative)
I take it you don't write much maths code, then? ;-)
There's a reason mathematicians don't write this:
and they write this instead:
The same reasoning is just as applicable when writing code.
You're right, but Raskin is wrong (Score:3, Informative)
In "Literate Programming" the comments are all important and the code itself is trivialized. The code, as Jef told me, is like "raisons in the muffin of the comments." There are paragraphs of verbiage which might go on about the history of the project, why certain features were discarded, etc., etc, and might not even explain what the following line or two of code was concerned with.
It's really very difficult to deal with code that has been written in this style ("literatized?" ) since the actual structure of the program is severly obscured. It serves as an example of how overdoing a good thing is usually a bad thing.
Jef was a nice guy, and I recommend his book, "The Humane Interface" for its many interesting ideas. His attempt to put them into practice in the Archy project http://rchi.raskincenter.org/aboutrchi/index.php/ [raskincenter.org], was not completed before his death. Even for that, Archy is very close to his vision.
But since Jef was in many ways an extremist, one can demonstrate in Archy his pushing of his concepts to the limit resulted in the end fully maching his goals. Somewhat like "Literate Programming", in fact.
Re:Debug code not comments (Score:2, Informative)
Basically, I write down anything that I don't want to have to figure out again. It saves me so much time with large projects. You have to keep this level of agressiveness up to keep the comments up to date, but if you get used to putting your thought processes on paper, then you'll get used to editting them on paper, too.
Good comments are good (Score:3, Informative)
Definitely not. No matter how clear your code is, it only gives you an idea of what is going on the small scale. You often need comments to describe your big-picture motivation. But the comments have to be good too.
Here's a classic bad comment:That's useless. But a comment can help:No matter how clear you write the code you're not going to get that much understanding without a comment.
It's just a simple example off the top of my head, but that's how I use comments. The code clarity is all that's needed to tell what you are doing, but comments can tell you why you are doing it. You need both for truly maintainable code.
Cheers.
Re:Use long variable names (Score:3, Informative)
Re:Even more annoying... (Score:5, Informative)
gg=G
and it will reindent a file for you....
I hate programmers who refuse to learn about their tools.
Re:Not necessarily comments... (Score:2, Informative)
That was MJD's POD is not Literate Programming [perl.com].
Re:The problem isn't lack of comments (Score:3, Informative)
Linus' Opinion (Score:2, Informative)
Re:Gotta document that code... (Score:5, Informative)
is obviously not useful
Not only is the comment not useful, it's factually incorrect... the behaviour of that line of code is undefined [msdn.com].
Re:The problem isn't lack of comments (Score:1, Informative)
Re:Gotta document that code... (Score:3, Informative)
First of all, he didn't properly handle errors, so if anything goes wrong, his object just sits there in memory (no garbage collection in VB6!). Our servers have been crapping out lately, so this was a valuable discovery for me. Second, when he fetches his data from Oracle, he inexplicably sets the lock type to "adLockPessimistic" (with a static, client-side recordset that doesn't get updated!!!) which locks the affected records until the recordset is done with them. Which I suspect means that if there's an error and the recordset doesn't get closed or set to nothing, the records will be locked until some timeout occurs. Another tip about why the server might be choking (lots of users hitting the same records, ha ha, what fun). And, on top of that, he's not cleaning up his objects, so it's not like the recordset ever releases the records in the first place. I mean, at some point they're getting released, but it's not HIS code that's doing it.
So, I rewrote the whole thing correctly, fixing the error handling and making sure objects were cleaned out, switching to a static recordset with optimistic locking, etc, shortening and speeding up the code. I might speed it up some more by making it readonly, I dunno. Thinking about it.
And, so I'd remember what I did and why, I added brief notes stating why I chose the lock and cursor types I did, why I used adUseClient instead of server, etc. In other words, I pointed out the nonobvious stuff that the code didn't explain.
I'm hoping that the next programmer to come along, who might not be that good at ADO, will read what I wrote and understand why it should be done a certain way.
I think good comments are about context, and sharing the thought process of the original programmer, and adding nonobvious info.
Sorry I didn't have code to share, but it's at work and it's late.
Re:Even more annoying... (Score:1, Informative)
ERROR = -1;
if( f(x) != ERROR ) ...
and not:
MINUSONE = -1;
if( f(x) != MINUSONE ) ...
Testing mystery numbers is bad practice. Any mystery number that you test for has some symbolic meaning. Like true, false, null... and so on.
Re:Top Ten Code Comment Do's List (Score:5, Informative)
Re:Even more annoying... (Score:3, Informative)
So tell them to go away and come back when it's properly indented. Point them at the tools they need to automagically indent their badly indented code. They'll never learn if you don't tell them that they have an unreadable coding style and explain to them why intenting is a Good Thing.
Re:Gotta document that code... (Score:3, Informative)
- Document every subroutine/method/macro/functional unit
- If you find yourself having to document a free-standing chunk of code, consider modularizing
- Write system/functional/etc. documentation seperately (in the same file in some langauges, but NEVER IN THE CODE) to give yourself a chance to abstract the concepts that the code represents.
- Add inline comments to free-staning code without modularizing, only when the reader's assumptions might be violated (e.g. I tend to document my use of POSIX time routines because they LOOK like Y2K bugs, but are not).
- When documenting routines, include the meaning of parameters and the meaning of the return value (if any) as well as the general function of the routine
- Avoid globals where possible, but document each when used
- Keep documentation well formatted so that it does not obstruct code visually.
Following these rules, I have never produced code which someone who knew the language I was programming in could not read and understand. When I write Perl code and use some large Schwartzian Transform, someone who does not know Perl might be confused, but I can't really stop and document every line of code for everyone who doesn't know the language. If I'm doing something particularly hairy that might not look sane to a reader who knows the language, then I comment it.There's code that I wrote 15 years ago that someone came to me a few years ago to ask about using in a college class, so I guess it works out ok
Re:Gotta document that code... (Score:3, Informative)
Re:Even more annoying... (Score:3, Informative)
= indent
G until end of document
vim has an excellent help system.
This is what it means, "learn your tools."