10 Commenting Mistakes Developers Hate (And How to Fix Them)

As programmers, we constantly encounter a wide variety of code comments, many of which hinder readability and maintenance.

1. Comments that contain contact information, TODO items, or requirement links

This style shows outdated habits; modern practice is to place such information in Git commit messages, issue trackers, or pull‑request descriptions. The examples below illustrate why these comments should be removed.

2. Comments that embed partial design documentation

These comments are problematic because their accuracy and completeness are uncertain, and they clutter the code. A better approach is to keep design docs in dedicated platforms such as GitHub Pages.

3. Comments that explain how instead of why

Explaining implementation details without the rationale is considered a bad practice. The following screenshot shows a typical "how" comment that should be avoided.

4. Comments that describe method usage, parameters, and possible exceptions

Rather than writing extensive usage comments, it is more effective to provide comprehensive test cases that demonstrate correct usage.

5. Comments that give special algorithmic explanations

These notes can be useful but should be managed together with the code, for example in Git commit logs, to avoid drift between code and comment.