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

Huh?

[tntguy]

These comments you speak of, they seem foreign and strange to me.

My favorite code comment not written by me

[dcarey]

I was doing some maintenance on someone else's code and came across this nasty set of like 8 nested if/elses. It was a bloody horrible hack. But the best part of all was the comment right at the top: /* Oh, fuck */

Don't do it!

[Anonymous Coward]

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.

In summary, DON'T COMMENT!

Gotta say it

[modi123]

/* no */

Example

[dduardo]

/*This loop starts at x is equal to 1 and continues while x is less then 5. x is incremented by 1 each time.*/ for( int x=1; x5; x++ ) { printf("Hello World\n");/*Prints "Hello World"*/ }

Practice what you preach

[ChrisF79]

I viewed the source on the site and nothing was commented :)

Comments are more important than Code?

[jetkust]

Comments are more important than Code?

I once tried writing code that was completely made up of comments. It was easy to write and all, but didn't work very well.

Don't comment

[i.r.id10t]

Don't comment at all, and just run it thru The Commentator!

http://www.cenqua.com/commentator/ [cenqua.com]

Re:Huh?

[bluelip]

"The code was hard to write. The code should be hard to read."

Was that some form of early DMCA or IP lockdown?

No

[rbarreira]

No, that first one should be something like:

This loop starts at 1, and to 5 it counts. It doesn't count to 6, nor it does count to 8. It does not count to 3 or 4, except in passage to 5. When it reaches number 5, the fifth number...

Re:Huh?

[TommydCat]

/* Please phrase your reply in the form of a comment. */ /* Thank you */

Things to always remember when commenting

[WillAffleckUW]

1. Never spelchezk.
2. Use randomly chosen variable names, or objects that resemble your favorite Orcs and Trolls from LotR - after all, everyone knows that a Lothlorien object will have farseeing ability, so it's obvious.
3. When instantiating something for the first time, never explain it - real programmers read the original object source.
4. If you do something complex, write a short pithy comment like /* magic occurs */
5. If you do something easy but you were drinking too much hot cocoa, write a long verbose description, and also mention how good the hot cocoa was.
6. Always include song lyrics to what you're listening to while you wrote the code.
7. Object inheritence means never having to explain the code.
8. Repetition is the best way to reinforce obvious things - so repeat the obvious thing since it's the best way to reinforce it.
9. If you break up with your girl/boyfriend, write about it in the comments - people really want to know.
10. If you're updating or modifying code, write your opinion about the original code in the comments. Use nasty words if you can.

All Depends...

[eno2001]

...on who is going to be reading the code after you are gone. Sadly, due to differing levels of expertise, there is no optimum method of commenting code. For some, this is a very useful comment (I'm using pound sign comment designation as an example):

# The main function starts here

or...

# This is a loop and it will run while a certain
# condition exists.

or...

# Don't forget to remove this section after
# I'm gone - Dan - 04/25/1995

Think about the children! ;P

Re:Comments are more important than Code?

[NialScorva]

At least you had no compile errors or core dumps, and I bet you didn't have any exploitable vulnerabilities either.

Re:My favorite code comment not written by me

[lukewarmfusion]

So you found that, eh? *evil chuckle*

I was in a similar spot a month or two ago and found some other company's comments - unhelpful as always - in the form of typed out sound effects.

# This function goes vroooooooommm-pop!

I have no idea why the developers put such comments there other than to entertain themselves as they sifted through their horribly written Perl.

Re:Huh?

[torpor]

/*
  * slashdot comment comment
  * 1.0.0 - torpor - init.
    */

#pragma KARMA_HACK // technically, also a comment. /* comments are fun. */ //code goes here..

Next on his list of things to write about

[deblau]

Successful Strategies for Crashing Your Website

Obfucksucated code contest

[jurt1235]

This kind of reviews are really destructive for my goal of winning the obfuscated code contest (http://www.ioccc.org/ [ioccc.org] can not read any further.

Re:Huh?

[MHobbit]

A TRUE Klingon warrior does not comment his code!

*ducks*

Re:No

[lboxman]

That's only appropriate if you're documenting python code...

Re:No

[legirons]

Not in the real world... more like:

//----------
// ReadSalaryData - reads table of salary values from database
// Parameters:
// - DB, database handle
// - Data, pointer to list
// Returns: Success
//---------
void DeleteUsername(char *Name)
{
...

Re:Huh?

[Kehvarl]

*ducks*

A true Klingon warrior does not duck.

A true Klingon warrior would have nothing to do with such a weak waterfowl.

Re:Huh?

[not-enough-info]

The user catalog is a perl database and we need to localize for how many countries? Then, today is a good day to die!

Re:Klingons and code documentation

[tomhudson]

1. Our users will know fear and cower before our software. Ship it! Ship it, and let them flee like the dogs they are!

Bill Gates is a Klingon? I thought he was a Borg?

Re:Things to always remember when commenting

[Reverend528]

haikus or other poems are also useful comments:

// nested switch statments
// with some inefficient code
// and memory leaks

Re:Huh?

[hhlost]

// TODO: add comments