Worst Practices for Code Commenting

Since software is often reused, readability and maintainability are important. Many engineers, though not all, would say commenting one’s code is an important or even critical part of achieving this.

Besides aspiring to best practices, it can be valuable to learn from bad practices. Here’s one author’s opinion on how not to comment:

  • Commenting every line:
  • unless you’re coding is some highly obscure language like assembly, you shouldn’t comment every line. Bad practice: describing what a for-loop does.

  • Comments are not an art project:
  • some coders like creating elaborate ‘clipart’-like figures using just ASCII characters. While fun, these create clutter, and can be annoying to maintain during changes.

  • Header Blocks:
  • can be used as an excuse to badly name and maintain classes, names etc.

  • Comments as source control:
  • it’s tempting to use comments to record or communicate information that really belongs in a version control system.

  • Comments instead of self-explanatory code:
  • most code should preferably be self-explanatory. Good practices include naming variables and functions in such a way that it’s clear what they do.