Successful Strategies for Commenting Your Code 500
LilG writes "Over at Particletree, Ryan Campbell writes about Successful Strategies for Commenting Your Code. His essay gives advice and examples on proper commenting, and details some different strategies."
var names (Score:3, Insightful)
I was skeptical at first regarding the topic (Score:5, Insightful)
I think it was Fowler who once went as far as to state that when you find yourself needing to document code in order for it to be understood (vs. thoroughness, completness, or document generation) you probably need to refactor your code.
How many times have we come across code like this?
public void bigFunction1()...
public void bigFunction2()...
Commenting (Score:5, Insightful)
And for crying out loud update the comments when you change code!
*grumbles about 10 year old code and 15 year old comments*
A comment on comments (Score:5, Insightful)
The following is an example of useless documentation:
frobWoggleFfloofMoing
public void frobWoggleFfloofMoing(String, String, String)
...
You see, running Doxygen over your header files may produce some output in HTML format, but it doesn't produce what I like to call "documentation." For instance, documentation would explain what is a Woggle, and when should it be Frobbed?
Thank you, and have a nice life.
How & Whys (Score:4, Insightful)
Comment the why, not the how.
Hopefully the code should be clear enough to pick out the how, but *why* you are doing something is never going to be apparent from the code itself - at best someone might be able to infer it, but that becomes especially tricky when time passes or a new person signs on.
Re:Don't do it! (Score:3, Insightful)
Don't EVER comment your code if you work for a company. That's a sure fire way to lose your job! If you don't comment your code then you are the only person who can understand it, making you indispensible.
Great idea! The myth of indispensibility is a great reason. May your next job be as a maintenance programmer in a Perl shop where the previous "indispensible" developer had his ass fired for threatening the boss and you get 50,000 lines of Perl dumped in your lap.
zerg (Score:5, Insightful)
Re:What makes a good Comment? (Score:5, Insightful)
As long as you're commenting the _real_ effect of the instruction, and not just mindlessly repeating what the mnemonic already tells the reader. I've seen lots of stupid assembly-language comments like "increments the A register". Gee, thanks - I couldn't have figured that out from the "INC A" mnemonic.
Re:I was skeptical at first regarding the topic (Score:3, Insightful)
Re:What makes a good Comment? (Score:3, Insightful)
Re:Commenting (Score:4, Insightful)
Re:Commenting (Score:2, Insightful)
Sure and when you get around to actually writing your code and you find out that it doesn't quite work as easily as you thought it should and you deviate from your comments then rarely does the comments get updated. After a few rounds of revision and testing the comments are a mere artifact and document how you original thought it should work.
If you see bad code don't comment, refactor please (Score:2, Insightful)
OK, it s not always possible and/or desirable. If it is not broken don't fix it. When I see comment in code because the developer don't understand what happening in 8 level deep statement or in the little function of 10000 lines of code, please fix the code.
there is basic rules to follow; not all exposed here it would be tooooo easy and me way too lazy :) :
Comments are there to
NB: I know javadoc, junit and metrics is for java but...
Re:What makes a good Comment? (Score:3, Insightful)
Not specifically regarding assembler, but you've just reminded me of the thing I absolutely hate the most which is people taking a chunk of existing code, comments an' all, tweaking the code to do something similar but different, but not updating the comments. Any typically the people (they ain't programmers!) who do this also use the existing function name but suffix it with a "2" or something -- I mean, why bother with a meaningful name? Someone might be able to understand the code!!
more than 60% (Score:2, Insightful)
Another problem ( I think I'm on a rant here ) is that some people say they want an engineer when what they want is a designer, they want someone to make their site look pretty, and they really don't care about functionality. They just figure "Its too technical for me so I must need an engineer."
(The situation isn't helped by people who use flash and call them selves an engineer)