http://developers.slashdot.org/article.pl?sid=05/11/30/1544256&tid=156&tid=8
I specially like this post:
http://developers.slashdot.org/comments.pl?sid=169760&cid=14147424
by Matt Ownby (158633)
I once read that a good comment will appear on every conditional branch or loop, and a good comment will also state the INTENTION for doing something, rather than what is actually being done (because the programmer can usually figure out what is being done). For example:
// i starts at 1 instead of 0 because we don't want to process the application's name (first argument)
for (int i = 1; i argc; i++)
{
printf("ARgument is %s\n", argv[i]);
} // AND with 0xFF1234 because that is the first set of bytes in the file header
if (u & 0xFF1234)
{
printf("File is valid.\n");
} // say file not found instead of invalid due to reason blah blah blah ...
else
{
printf("File not found.\n");
}
Also, by Ckwop (707653):
http://developers.slashdot.org/comments.pl?sid=169760&cid=14147437
A comment should tell you why something is in place rather than what the code is doing:
A trival example:
Don't do this:
public bool CheckSmsValue(Account smsAccount)
{
// Check tarriff is null
if (Account.Tarrif == null)
return;
...
}
Do do this:
public bool CheckSmsValue(Account smsAccount)
{
// 30-11-2005 Fixes a null reference exception that occurs later on if no reference is available.
if (Account.Tarrif == null)
return;
...
}