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."
I sometimes get, uhh..."creative", before I program. End up with variable names like "$iHateThisProgram" and "$godFinWorkAlready"
Anyone else experience this phenomenon?
--------------
David O.
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.
when you still know what is does after 6 months!
this sig has intentionally been left blank
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
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?
int main (int argc, char argv[][]) {
int j;
int i = 7;
char *h = argv[1];
for (j = 0; j < i; ++j) {
q[j] = malloc( sizeof( foo_t ));
}
memcpy( p, &((*((x+i)+k[i->e]).sin_addr),
sizeof(&((*((x+i)+k[i->e]).sin_addr)));
return 0;
}
STOP ME BEFORE I POST AGAIN!
Didn't you mean:
REM Since you are slow, you failed. Commit Hari-kari
...?
STOP ME BEFORE I POST AGAIN!
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.