My Commentary on Code Comments

For many years I have worked with various humble companies and clients, giving me the chance to encounter many programmers, each with a unique style, and each project with its own distinctive elements.

These intersecting traits led me to reflect on memorable code comments I have reviewed, updated, or improved, focusing not just on the logic but on the impact of developers' annotations.

Because Carol told me to do this

// Because Carol Told Me to Do This

This cryptic comment left me wondering who Carol is and what she asked the developer to do, rendering the comment meaningless to outsiders.

Large blocks of commented-out code

Sometimes entire sections of code are block‑commented out in the middle of methods, forcing readers to scroll extensively to continue, which is frustrating.

Just for fun

// make sure it's correctly formatted, because in javascript things
// like '7' or '4.3' or 'derpdy do 77' are valid dates
// seriously, try it out for yourself: Date.parse('derpdy do 77')

This JavaScript comment warns about the quirks of Date.parse() and adds a humorous note.

Apology

// Sorry for what you are about to see

Sometimes developers apologize in comments when they know the upcoming code is sub‑optimal.

Only coding around it

// Doing this to "not do anything to effect Eric and Steve's code"

The comment references colleagues Eric and Steve, indicating a need to avoid affecting their code.

Commenting for the sake of commenting

return true; // returns true

This redundant comment adds no value because the code is self‑explanatory.

Incorrect comment

// Always returns false
public boolean isActive() {
    return true;
}

Providing false information in a comment can be more harmful than having no comment at all.

Novel‑like comment

/**
 * This is the widget method which will process the list of
 * widgets from the widget controller and service in order to
 * handle pre‑processing (where the widget information is
 * compared against the average widget history), actual
 * processing (where the quarterly, monthly and week attributes
 * are updated) and all of the post‑processing (which include the
 * analytical metrics and audit table updates) aspects. It is
 * important to remember the widget rules around leap year where
 * the cost to transfer rate is 75% adjusted to the annual rate in
 * order to account for the extra day. When this happens, the
 * process will throw the LeapYearException which will need to be
 * validated by the application support staff. Failure to do so will
 * end up causing issues with the ME-4110 report.
 */

Such overly detailed Javadoc blocks often belong in separate documentation rather than cluttering the code.

Conclusion

While many resources discuss how to write good code comments—or even how to avoid them—this article shares a handful of amusing and instructive examples from over twenty years of development experience, reminding readers to keep comments purposeful and concise.