Slashdot Mirror
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."
ie,
while (1) {
}
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.
"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.
Unless the code is Perl ;)
Yes, it is published by Microsoft
*Abruptly stops the finger from clicking the link*
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.
If there is hope, it lies in the trolls.
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
$StringPlusOne = $DollarDivideBy * $HashSemicolon + 8;
print "$EndQuote Semicolon new line";
getURL "http$Colon$Slash$SlashSlashDot${dot} org$slash";
...
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.
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.
I've had enough abrasive sigs. Kittens are cute and fuzzy.
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.
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 :-).
//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.
:-)
One of my favorites was a temporary function pointer named funcSoulBrotherInDaHouseNow. The same guy made a function named BashTheProcessor() with the comment
None of these symbols are exported, so the world at large was spared until now.
Staying anonymous to protect the identity of my coworkers.
Bah, he was hard to work with, he was easy to terminate.