How to Write Comments 556
Denis Krukovsky writes "Should I write comments? What is a good comment? Is it possible to comment a class in 5 minutes? See "
Everybody knows that good code is self documenting- which is why my prof in college demanded we write in Ada. I instead suggest commenting in haiku.
Re:Reading (Score:3, Interesting)
How many times can we see a line like this... that's just writing comments without any reason.
I prefer function header comments which describe what the piece of code as whole does. Not everyline, as teachers say it should be done.
Re:MOD PARENT UP. (Score:1, Interesting)
Tell that to Gary Kildall [wikipedia.org]
If you don't comment it will come back to haunt u (Score:2, Interesting)
Commenting code is good on several fronts. Firstly, even the programmer can't remember what the hell he did just a few weeks ago, let alone several months or years. You will thank yourself. Secondly, anyone else who has to modify that code will track you down to explain something if it's not commented. If you use source control, they will find you. And thirdly, it's easy to do while you're coding and not after. It's almost a freebee.
gasmonso http://religiousfreaks.com/ [religiousfreaks.com]Re: Good code is self documenting... (Score:5, Interesting)
Here's the original code:
L = Cholesky(cov0);
th1 = L.i() * th0;
lrt = (th1.t() * th1).Trace();
which is supposed to compute the same answer as the code:
lrt = (th0.t() * cov0.i() * th0).as_scalar();
I do agree that in general code should be self-documenting when possible, but sometimes you need a few lines of comments to explain a single line of code, or a few paragraphs of comments to explain a few lines of code. I added 17 lines of comments to that part of the program to explain 3 lines of code.
On code commenting (Score:1, Interesting)
Specifying the "what" in a human-readable form is a strength of some languages including COBOL and Ada. No one (hopefully) would argue that C-based syntax is particularly intuitive, and that common practices that emphasize brevity also are focused on reader comprehension. Where the language doesn't aid comprehension of the "how" or "what", comments should help.
In 25+ years in this business, I've seen everything from
to code preambles that resembled War and Peace.dave
Re:Comment every conditional branch or loop (Score:3, Interesting)
You've heard of constants?
Seriously, this is not good code: if (u & 0xFF1234) - what the hell is u?
Exactly. I was thinking the same thing.
Clearly labeled abstraction is self documenting and is just better.
Instead of if (u & 0xFF1234), why not have a macro like #define VALID_HEADER(a) ((a) & 0xFF1234) and use if (VALID_HEADER(u)). u might be an OK variable, maybe not.
One thing I do with perl code is instead of making a complex regexp that is expanded with inline comments and whatnot, I just throw a commented line or more of what is trying to be matched. Like if I was parsing a log file for something like:
Nov 30 10:15:01 localhost anacron[5454]: Job `cron.daily' started
I would throw that as a comment, and then throw a regexp on it that may look like hieroglyphics but say something like $mon $day $time $machine $command $pid $msg. If it works, nobody cares. If it doesn't (format changed or whatever) no comment in the world is going to make it easier to debug any differently than having a sample of the expected input.
NEVER do dumb shit like:
int i;
Its also good to document the basic ins and outs of functions, and the by products of it. If the function destroys the input. Let me know. If the function returns something special in the case of an error. Let me know. If the function takes arguments, let me know what those are. If the function returns malloc()ed data that I need to free, let me know. If I need to provide enough malloc()ed info going into the function, let me know.
Feel free to substitute "me" with "you the programmer" in case you ever look back at your own code.
Another thing to avoid. Don't make code reusable with copy and paste. That kills me, and I had to come behind some "senior" programmer's code before where that was done 3 or more times on huge modules where each one was subtly modified. I would fire someone on the spot for that if they were a "senior" programmer.
Oh, and how about this. Reading the documentation first and/or knowing the language/API/specification before you start writing code. Another different "senior" programmer I worked with though he was clever to rewrite the CGI specification and do his own parsing of URL arguments instead of using & and = signs.
Thank the FSM that I don't work for those companies anymore.
I never thought that programming was that terribly difficult. Working with other programmers definitely is.
Re:Haiku Commenting? (Score:1, Interesting)
Since then I either write an architecture document when the code is finished or if I make an addition I write up a short semi-rambling essay on why the code is structured the way it's structured in the comments at the top.
Not only easier on others, but also on myself if I have to go back.
Re: Good code is self documenting... (Score:3, Interesting)
Overcomment everything (Score:5, Interesting)
Some comments I've written:
Here the purpose of the comments is to explain the math.
All code should have well-written comments. As Wirth pointed out years ago, people who can't express themselves well in their native language are generally poor programmers.