Developers: How to comment your code

[rickg22]

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:

Code

// 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:

Code

public bool CheckSmsValue(Account smsAccount)
{

// Check tarriff is null
if (Account.Tarrif == null)
          return;
...
}

Do do this:

Code

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;
...
}

Simon.

[Michael]

Interesting. Thank you for providing this useful information.

Best wishes,
Michael