//Comments about comments

Although they are usually enforced by coding standards, and I strongly agree, I believe code comments should be minimized for many reasons:

  • Except for XML comments of methods and classes, most comments are not affected by automatic refactoring tools
  • Most developers forget to update comments after updating code
  • Sometimes they mix with temporarily commented code
  • Every one adds one or more additional lines to the source code
  • They might make the code ugly
  • They implicitly admit that your code cannot express your ideas
  • They cannot be validated by type checking or unit testing
  • Most of the times, there are more better alternatives than comments

Yet I believe they are highly needed in these cases

  • Writing important messages to self or others
  • Writing code review comments
  • Writing //TODO tasks for self or others
  • Writing failed trials to avoid reusing them later while refactoring
  • Writing justification for code that might not appear logical at first look

And finally here are some cases when comments can be replaced by better alternatives

if (i >= 5) // number of orders
if (numOrders >= 5) // <-- better option: use meaningful var names
if (custType == 5) // credit customer
if (custType == CustomerTypes.Credit) // <-- better option: use enums

if (custCredit >= 30) // credit over 30%
if (OverCredit()) // <-- better option: use methods (or properties)

private bool OverCredit()
{
    return custCredit >= 30;
}
if (a == b)
{
    if (d == c)
    {
        // ... long lines of code ...
    } // if (d == c)
} // if (a == b)

// Most decent IDEs highlight matching braces when u select one of them
// Also long lines of codes should be avoided, use methods
// begin saving data
    // ... long lines of code ...
// end saving data

#region Saving data               // <-- better option: use regions
    // ... long lines of code ...
#endregion

SaveData()          // <—- another better option: extract as method
// Modified by modeeb @ Feb 6, 2009 02:32:12 PM
// better option: use a version control system that have "blame" or "annotate" functionality
Advertisements