Why Good Code Comments Matter: Debunking the No‑Comment Myth

Bad Code

People claim that comments are unnecessary because the code should be clear enough. While code quality matters, no one writes perfect code, and it degrades over time—especially after six months of not touching it.

When revisiting old code, you often wonder about the original intent, and tools like git blame reveal that the code was written by you, yet you may have forgotten why.

Even if a project feels clean in your head, after months or when a critical bug appears, the lack of comments makes the code fuzzy for anyone trying to debug.

Writing even simple comments is not a bad practice; it provides invaluable context that pure code cannot convey.

Missing Comments Make Code Harder to Understand

Some argue that removing comments forces clearer code, but this often backfires, producing more complex code with unnecessary function extractions and obscure names that require readers to jump around.

Short, descriptive function names cannot replace longer explanatory comments; without them, developers may misinterpret intent.

Small functions can still cause confusion, especially when they expose implementation details that should remain hidden.

For example, overly terse variable names like usernameStrippedOfSpacesWithDotCSVExtension illustrate the need for comments.

There Are No Bad Comments

// 实例化一个错误对象
var err error

A clear comment like the one above is harmless and can save hours of work.

In practice, code without any comments is rare, and even minimal annotations are preferable to none.

Any Comment Is Better Than No Comment

Images illustrate the absurdity of changing implementation without updating external labels.

Even with modern code reviews, mismatched comments and code still occur, leading to bugs.

For instance, a comment for client.SetKeepAlive(60) described the parameter as seconds, but Go treats the integer as nanoseconds unless a time.Duration is used, making the comment misleading.

Why?

The most important comments explain the "why" behind design decisions, constraints, and trade‑offs that cannot be inferred from the code alone.

While function names convey "what" a function does, "why" comments capture experience, business rules, and system limitations, saving future developers time and preventing errors.

Testing

Tests are precise but often verbose, covering only narrow cases; they do not replace documentation that explains intent.

When understanding code requires reading many test cases, it signals a need for better comments.

Conclusion

Distinguishing useful from useless comments is difficult, so it is safer to err on the side of writing more comments.

You never know who will read your code next; comprehensive comments can save them significant time and avoid bugs.

Write as much as you think is excessive, then add a bit more—that amount is likely just right.

Link: https://npf.io/2017/11/comments/

(Copyright belongs to the original author, please delete if infringed)