Successful Strategies for Commenting Your Code

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."

Comments

var names

[rockytriton]

My best strategy is intelligent variable names and clean simple code. -- http://www.dreamsyssoft.com

I was skeptical at first regarding the topic

[Anonymous Coward]

But when reading the article I was glad that the very first item was SELF DESCRIBING CODE. The most important part of code documentation is the code iteself IMHO.

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()...

Re:I was skeptical at first regarding the topic

[lgw]

Self describing code is great for explaining what the algorithm is, but sometimes it's just not going to be clear how a function fits into the big picture (because the problem you're solving is a mess), and sometimes you need a clever algorithm that solves the problem in a non-obvious way. The mapping of code to algorithm may be self-describing, but that doesn't mean the mapping of algorithm to problem space is (or that it can be made so - in many cases it's the problem being solved that needs the all the documentation it can get).

Commenting

[Hamster Of Death]

Write the comments first, then add the code. That way you'll get a better grasp on the problem you're solving. If your comments don't explain the problem or someone else can't solve the problem using your comments then you'll probably need to rethink your approach.
And for crying out loud update the comments when you change code!
*grumbles about 10 year old code and 15 year old comments*

Re:Commenting

[bmwm3nut]

exactly! in fact, this was taught to me by a senior programmer who said: "you should never document your code, your should code your document." in projects where i've followed that rule, i've had many fewer problems than ones where i jumped into the code quickly.

Re:Commenting

[truckaxle]

Oh hey I have maintained code written with this technique

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.

A comment on comments

[Jeffrey Baker]

Dear Doxygen and JavaDoc users,

The following is an example of useless documentation:

frobWoggleFfloofMoing

public void frobWoggleFfloofMoing(String, String, String)

Frobs the Woggle

...

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

[Anonymous Coward]

It's been said before, but I find the best advice I've ever gotten on commenting code is very simple -

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!

[treerex]

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

[Lord Omlette]

Ask someone else to look at your code. Every time they pause while scrolling, touch their chin, squint their eyes, furrow their brows, etc., it means you need a comment.

Re:What makes a good Comment?

[mOdQuArK!]

You really should comment every line of assembly, even when you just increment a register,

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:What makes a good Comment?

[lgw]

I couldn't agree more. Some people just need not to program.

If you see bad code don't comment, refactor please

[BlueYoshi]

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 :) :

• Think before coding
• good variable and function names
• short function is desirable
• don't do more than 4 level-deep statement
• use javadoc for describing function and their parameters
• Think before coding
• use metrics to analyze code
• use junit or other technique to have simple example of use of the code.
• Think about the children^W maintainer
• Think before coding (did I mention it?)

Comments are there to

• javadoc standard formal description for procedure paremeter,...
• tell Why not How
• explain code to avoid bugs in a library or third party code (if (UserAgent == NETSCAPE4) heightOfBox = heightOfBox * 10 /7) // to go around "feature" in netscape about the calculation of (...) see [browser bug workaround 3.2.5]
• place inside method that need to be implemented or overrided
• to explain very particular code for specific constraint like optimization or obscure technique but that need to be avoided and maybe the comment could be a reference to some more advance documentation

NB: I know javadoc, junit and metrics is for java but...

Re:What makes a good Comment?

[Zaiff Urgulbunger]

Or worse yet, lying.

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%

[lebow]

I recently took a contract somewhere as an 'engineer' where I was probably the only one who had an engineering degree. Also the work I was doing was far from engineering (web programing). Also I've been on interviews where the client sets me up to talk with their "engineer" who probably doesn't even have a college degree. The problem I've run into is that many times the ones doing the hiring have no idea what they are talking about. To them the engineer is the guy who can use the terminal, or can write HTML by hand.
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)