Code comments (tips to comment your code)

Tips to comment your code

 

For each class, include a brief description, author and date of last modification

For each method, include a description of its purpose, functions, parameters and results

Break code blocks into multiple "paragraphs" that each perform a single task, then add a comment at the beginning of each block to instruct the reader on what is about to happen.
// Check that all data records
// are correct
foreach (Record record in records)
{
    if (rec.checkStatus()==Status.OK)
    {
        . . .
    }
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

For multiple lines of code with trailing comments, align the comments so they will be easy to read.

const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F;    // mask bit TCP

Some developers use tabs to align comments, while others use spaces.  Because tab stops can vary among editors and IDEs, the best approach is to use spaces.

Avoid obvious comments such as:

if (a == 5)      // if a equals 5
    counter = 0; // set the counter to zero

This wastes your time writing needless comments and distracts the reader with details that can be easily deduced from the code.

When working on code as a team, adopt a consistent set of tags to communicate among programmers.  For example, many teams use a “TODO:” tag to indicate a section of code that requires additional work:

int Estimate(int x, int y)
{
    // TODO: implement the calculations
    return 0;
}

Tag comments don’t explain code; rather they seek attention or deliver a message.  But if you use this technique, remember to follow up and actually do what the message is asking.

Add comments while you write code and it’s fresh in your memory.  If you leave comments until the end, it will take you twice as long, if you do it at all.  “I have no time to comment,” “I’m in a hurry,” and “The project is delayed” are all simply excuses to avoid documenting your code.  Some developers believe you should write comments before code as a way to plan out your ultimate solution.  For example:public void ProcessOrder() 
{
    // Make sure the products are available
    // Check that the customer is valid
    // Send the order to the store
    // Generate bill
}

When it comes to commenting code, think not only about the developers who will maintain your code in the future, but also think about yourself.  In the words of the great Phil Haack:

“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”

As a result, we ourselves will be the first beneficiaries (or victims) of our good (or bad) comments.

One of the basic principles for many developers: Let your code speak for itself.  Although one suspects this movement is led by programmers who do not like to write comments, it is true that self-explanatory code can go a long way toward making code that’s easier to understand and can even render comments unnecessary.  For example, the code in my Fluid Interfaces article shows how clear self-explanatory code can be:

Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );

In this example, comments are not needed and would likely violate tip #4.  To facilitate readable code, you might consider using proper names (as described in the classic Ottinger’s Rules), ensure correct indentation, and adopt coding style guides.  Failure to comply with this tip may result in comments that seem to apologize for bad code.

Other links:

http://particletree.com/features/successful-strategies-for-commenting-code/

http://freshmeat.net/articles/you-are-expected-to-understand-this

http://www.google.com/search?q=coding+style+guides&ie=utf-8&oe=utf-8&aq=t&rls=org.mozilla:en-US:official&client=firefox-a