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

5 thoughts on “//Comments about comments

  1. Shady Youssef says:

    Nice piece deeb,

    IMHO the number one value for inline comments and documentation is to document the assumptions made by the programmer while implementing this code.

    The final program is the result of two ingredients,

    1) The programmer understanding of requirements (not just the requirements)

    2) The assumptions, and rule of thumbs and tricks applied by the programmer while implementing the software. Those help spotting miss conceptions about the requirements as well

    Usually, other people (actual others or the same person but at a later time) would fail to understand the source code functionality and behaviour because of missing the later ingredient. Then, even neat requirement gathering and documenting techniques and systems won’t help.

    The tradeoff is, if you do heavy refactoring, you should consider the comment as part of your code, otherwise, out dated comments can cause more harm than help. Tradeoffs are unavoidable, and managing them is what engineering is all about.

    Keep the good work deeb

    Like

  2. @Mohammed Safwat: Is your critic your enemy or your friend? I think it depends on whether they improve you or degrade you. This case, they may be improving you.

    Like

  3. Mohammed Safwat says:

    I think it depends also on their intention. Maybe it’s just my feeling is that they’re offensively criticizing me.

    Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s