Code commenting? Try Business Commenting.

Jeff has a good post here about code comments and that they shouldn't be used as crutches:

Coding Horror: Coding Without Comments

I agree with the article, but one thing I rarely hear mentioned is that it's often more interesting to comment the business justification than it is to comment the code. Jeff goes some way towards suggesting this when he says to comment the "why", but for many people that translates to "Why did I write the code this way?".

I often find that code I'm maintaining is missing comments regarding the business logic. Rather than "Why is the code designed like this?", something like "Why is the business process designed like this?"

This becomes most useful when you look at unfamiliar code (your own, probably) and decide that the easily-digestible code is nevertheless doing something you are sure is silly, and you change it. Big mistake.

Example of a code architecture comment:

    1: // We cache these values because they only change once per
    2: // week or so.

Or:

    1: // We lazy-load these properties because they're rarely used
    2: // and they chew up a decent amount of RAM.

 

Example of a business architecture comment:

    1: // We copy the lab owner on this mail because even though
    2: // they don't own this resource, they wanted to be aware
    3: // of changes. See bug 54321 for request and history.

Or:

    1: // This used to delete items older than 30 days, but
    2: // bug #65432 requested that an exception be made for
    3: // items that are of type X.

 

All are useful, but I find the second type are rarely used. They become more valuable as the code ages.

 

Avi