What is Well-Commented Code?

WannaBeGeekGirl queries: "What exactly is well-commented code anyway? Can anyone suggest resources with insight into writing better comments and making code more readable? After about six years in the software development industry I've seen my share of other people's code. I seem to spend a lot of time wishing the code had better (sometimes _any_) comments. The comments can be frustrating to me for different reasons: too vague, too specific, incoherent, pointing out the obvious while leaving the non-obvious to my imagination, or just plain incorrect. Poorly or mysteriously named variables and methods can be just as confusing. In a perfect world everyone would follow some sort of coding standards, and hopefully those standards would enforce useful comments. Until then, any suggestions for what you, as a programmer, consider to be good/useful/practical comments? Any suggestions for what to avoid? Also, I usually work with C++ so any resources/comments specific to that language would be too."

Variable Names

[ludey]

I sometimes get, uhh..."creative", before I program. End up with variable names like "$iHateThisProgram" and "$godFinWorkAlready"

Anyone else experience this phenomenon?

Describe before you apply

[inflex]

I like to see comments where the function of the next code block is well described in a continuous comment block. Additionally, any further specific comments can be placed at the end, or on top of the lines in question. It's simple enough, and permits comment/documenting-scrapers to produce some potentially useful documentation.

ie,
// Foo():infinite loop
// We attempt to complete an infinite loop
// here as quickly as possible, in order to
// remain true to Linus's statements of
// being able to do them faster with linux.
while (1) {
... // Oooh, this is a fancy line, watch out for it doing nothing.
}

Use plenty of expletives

[oingoboingo]

Well commented code should definitely contain a liberal smattering of four-letter expletives, eg:


// no fucking idea how this works
obj.doMagic();


or...


//bet those fucking lazy cunts in the QA team don't pick this up
fileSystem.delete();


When your code is released as open source and becomes famous, people can amuse themselves by searching through the source code to find all the hidden expletives, sort of like easter eggs. If you work for a commercial organisation, you can sit back and enjoy the panic as the QA and release teams sweat it out trying to track down every last filthy utterance before shipping to a fucker...errr..customer.

Re:Just tell me what a section of code is for.

[inflex]

"I've never had to deal with 'obfuscated' code so I don't know about onscure variables, etc"

I thought Perl was the most efficient self-obfusicating code ever.

Re: Comments are evil.

[dorward]

The best comment is the code.

Unless the code is Perl ;)

Examples..

[popeyethesailor]

# all of these will also get moved elsewhere

# this is the worst damned warning ever, so SHUT UP ALREADY!

# Keep your friends close but your enemies closer.
# Or ignore them, we don't care.

# You know, we do assume comments are linear -Brian

Refer here [slashcode.com] for further details:)

Re:Code Complete

[jsse]

Yes, it is published by Microsoft

*Abruptly stops the finger from clicking the link*

Document abnormal behaviour

[tve]

1. Adopt some set of coding conventions. For instance, always return 0 on success/in the normal case.

2. Use informative variable and functionnames. Short names are preferred, but make sure it's clear what you mean. If it's impractical to fit all the required info into the var- or functionname, add a comment explaining the intended purpose of the variable/function.

3. Use small functions! Split actions up into logical steps. In combination with 2 this will help make your code a lot more readable, removing the need for many comments. Like Linus says: "The maximum length of a function is inversely proportional to the complexity and indentation level of that function."

4. Document any abnormal behaviour. For instance, if you've adopted the convention that functions return -1 on errors and you have a function that differentiates between different errors by returning either -1 or -2, document what the abnormal return values mean.

5. If the overall purpose of a group of functions (e.g. in one sourcefile) isn't obvious, add a general comment that explains the big picture. Code is much more readable if you know what it's trying to do.

it is well commented code...

[sirius_bbr]

when you still know what is does after 6 months!

My favorite comments

[bentini]

I personally despise comments such as:

i++; //increments the variable i

I think that they are unclear and do not properly explain the situation. Remember, you're writing so people can UNDERSTAND the code, not so that you can impress them with how smart you are. Instead, strive for a comment like this:

i++; /*changes the value stored in the space referred to by i to be the sum of the old value stored in the space referred to by i and the constant 1. Note: In C, this may cause what is known as a "silent overflow" if the value is too large, and go so far as to make a large positive value into a larger negative one. Oh my!

This way, people who read your code not only understand your program, but all programs. I really think that each function you write should repeat a semester's worth of computer science theory and programming practice, so that anyone who reads your code will learn from it. Remember, not everyone knows idioms, and why should they? And since we all write open source on slashdot, many novices are going to have their introduction to any computing environment by looking at the code you write at any point.

Your most humble and obedient servant,
Dan

Re:Use plenty of expletives

[Zocalo]

Well the linux kernel certainly qualifies then...

[admin@frodo linux-2.4.9-31]# grep -r [Ff][us]ck * | wc
134 1327 10723

Detection of the other expletives is left as an exercise for the reader...

Re:Code Complete

[Anonymous Coward]

You can hardly call yourself a professional software engineer if you have not read this book.

Since the people who wrote the book could not possibly have read it before they wrote it, then when they wrote it they had no right to call themselves professional software engineers. Why should I read a book that was not even written by professional software engineers?

Re:Use plenty of expletives

[Anonymous Coward]

Until someone runs nm on your executable and finds some "funny" variable names.
Funny variable names are sometimes related to say specific bugfixes a certain individual or customer has demanded.

I know one person where very large customer demanded a specific and very idiotic new feature to the software, due to the customer being an idiot.

Executable was not stripped.

The variable name to control this feature in certain functions was thus called IsAFuckingIdiot .

Customer by convention always ran nm on all new executables they installed.

Customer got very upset.

Well-commented code...

[Serial Troller]

int main (int argc, char argv[][]) {
int j;
int i = 7; /* FIXME: should be 6? */
char *h = argv[1]; /* FIXME: segfault if no argv[1] */

for (j = 0; j < i; ++j) {
/* TODO: Make this actually work */
q[j] = malloc( sizeof( foo_t )); /* FIXME: often segfaults */
}

/* FIXME: too drunk to figure this one out now */
memcpy( p, &((*((x+i)+k[i->e]).sin_addr),
sizeof(&((*((x+i)+k[i->e]).sin_addr)));




/* FIXME: too much whitespace */


return 0; /* FIXME: always 0? */
}

Re:Variable Names

[peddrenth]

$StringPlusOne = $DollarDivideBy * $HashSemicolon + 8;

print "$EndQuote Semicolon new line";

getURL "http$Colon$Slash$SlashSlashDot${dot} org$slash";

...

Re:reply

[Serial Troller]

Didn't you mean:

REM Since you are slow, you failed. Commit Hari-kari

...?

Re:Code Complete

[Anonymous Coward]

They must have read it in the process of writing it; so they were not professionals before, but they were after. But my opinion doesn't count for much -- I haven't read it -- I can hardly call myself a professional software engineer.

Re:Coding Standards

[GigsVT]

Other things, such as always including { and } in C, and putting them alone on their own line

Phew, I thought I was alone. I'm glad it makes sense to someone other than myself to actually have the braces line up vertically.

Re:Worst comment I ever saw

[IainHere]

Top of a huge listing of nasty code: /* I don't do comments */ I knew that tears would be my only comfort in the coming days.

Re:Variable Names

[Anonymous Coward]

I've seen some of these in real world code, and they're not too annoying (unless you're trying to figure out what the code does :-).

One of my favorites was a temporary function pointer named funcSoulBrotherInDaHouseNow. The same guy made a function named BashTheProcessor() with the comment //Shareef don't like it!. Another programmer named a miscellaneous callback YouWantFriesWithThat(). I was guilty of leaving around the comment // printf -- output function of kings for no reason whatsoever.

None of these symbols are exported, so the world at large was spared until now.

Staying anonymous to protect the identity of my coworkers. :-)

Re:Variable Names

[SecurityGuy]

Bah, he was hard to work with, he was easy to terminate.