Some Comments on Comments

Code is communication, and comments can make a world of difference when it comes to making code clear and readable. Every seasoned developer has seen code that could have been made clearer with a few well-placed comments. At the same time, it isn’t unusual to find code that is littered with comments that are stale, unclear, unhelpful or just downright irritating.

Nothing can be quite so helpful as a well-placed comment Robert C Martin

Knowing when to comment and how to make a comment is an art, and one that clearly separates good programmers from poor ones. It is worth taking time, then, to review our practice in comment-writing. This is particularly true for those of us who have been around for a while. Coding practices and technologies have changed, and some of our old habits are inappropriate in modern programming environments.
The rest of this article outlines my current thinking on code comments, based on my research and experience as a programmer.

The Purpose of Comments

The purpose of comments is to help to make code readable.
For this reason, comments should be:

  • Terse
  • Readable
  • Helpful
  • Correct
  • Unambiguous
  • Maintainable
  • Placed as near as possible to the code that they’re commenting on

Unhelpful Comments

Comments that should be code

As far as possible, code should be self-describing. This implies that comments should explain why, because code already explains how.

Comments do not make up for bad code Robert C. Martin

  • Comments should not repeat what the code already says, for example:

  • Where possible, refactor code to eliminate comments
    • Better function / variable names can eliminate the need for comments
    • A simpler architecture or structure requires less commentary
    • Shorter methods eliminate the need for closing brace comments, like this:

    • Split functions / classes into smaller units to eliminate comments that act as section headers or division markers

Comments that should be part of source control

…and if you aren’t using source control then you already have a bigger problem than bad comments!

  • Attributions (developer’s names)
  • Code version numbers
  • Journal comments (who did what and when)
  • Commented-out code
  • History of changes, like this:

Misleading comments

One of the biggest problems with comments is that they rot over time. The comment you write today may not match the code you write tomorrow.

  • Ambiguous or unclear statements
  • Outdated information
  • Comments that don’t apply to the present context
  • Information that applies only to specific cases
  • Comments that are just plain wrong

Comments that create unnecessary work for the author / maintainer

If comments take up too much time to maintain then they are less likely to be maintained.

  • Non-trivial formatting. Insisting, for example, that all comments are in neat boxes made of asterisks
  • Mandated comments – that your boss / process / toolset tells you should be there but which add no real value, for example:

  • Markup in comments (except when it is required by tools that generate documentation)

Comments that create unneccesary work fort the reader

  • Noisy comments
    • Comments that contain much information / irrelevant information
    • Chatty comments. Blah, blah, blah.
  • Poor spelling / punctuation in comments
  • Non-local information (such as information how callers will use a value returned from a function – that’s the caller’s business)

Unprofessional comments

  • Anything offensive, derogatory or insulting
  • Jokes / cultural references should be included sparingly, sensitively and kept short and/or clearly delimited as such

The practice of inserting jokes or cultural references in comments is a matter of some debate. Some people think they are invariably unprofessional, as they convey a lack of seriousness and waste time for both their authors and readers. Others (myself included) feel that they are conducive to a good working atmosphere. However, they should be easy to skip over for readers of the code, and should never risk your professional reputation nor that of your employer/customer.

Beneficial Comments

File headers

  • Copyright and other legal notices (everything else can be omitted)

Explanations and clarification

  • When you can’t explain something in code (by using a function name, for example)
  • Explanation of the intent of code
  • Clarifying the reason for a decison
  • Clarification of code you can’t alter, like library call results

To draw attention

  • Warnings of consequences
  • Drawing attention to important things that appear inconsequential

Comments parsed by development tools

  • TODOs
  • Documentation markup

Comments that save the reader time

Some of this last set may be a little controversial, but I find them beneficial:

  • Brief explanations of concepts, algorithms etc. so save the reader referring to external documentation
  • Comments that help interpret the solution in terms of the problem domain
  • Comments that signpost external documentation (such as urls)

Further Reading

  • “Clean Code” by Robert C. Martin

One thought on “Some Comments on Comments

Leave a Reply

Your email address will not be published. Required fields are marked *