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:
- Comments are not an art project:
- Header Blocks:
- Comments as source control:
- Comments instead of self-explanatory code:
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.
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.
can be used as an excuse to badly name and maintain classes, names etc.
it’s tempting to use comments to record or communicate information that really belongs in a version control system.
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.