Can You Write Clean Code Without Comments? Strategies to Eliminate Bad Annotations

Every programmer hates two things: reading code without comments and writing comments. The article asks how to solve both problems at once—eliminating the need for comments while avoiding criticism for missing annotations.

Why Reduce Comments?

Comments indicate that the code logic is not clear enough, making it hard for others to understand the intent.

Comments are difficult to maintain; after a task is finished, they often become outdated, leading to mismatched documentation.

Reducing comments forces a review of code structure and encourages code simplification.

Common Bad Comment Types

Redundant comments : Adding notes for obvious operations, e.g., "// add info to list".

Verbose comments : Over‑explaining logic, turning code into a secret that only the comment can reveal.

Layer‑replacing comments : Using comments to compensate for poor function decomposition instead of extracting clear methods.

Nonsensical comments : Comments that have no clear relation to the code they accompany.

Better Approaches

Instead of relying on comments, write self‑descriptive code: use meaningful variable and method names, apply consistent coding style, break logic into small, well‑named functions, and leverage utility methods such as Objects.requireNonNull() to express intent clearly.

"Comments Do Not Make Up for Bad Code" – Robert C. Martin, Clean Code

ChatGPT’s Tips for Comment‑Free Code

Keep code concise so it is easy to read.

Use descriptive names for variables and functions.

Follow a consistent coding style (indentation, spacing, naming conventions).

Break code into small, reusable blocks.

Write self‑describing code that conveys purpose without extra notes.

While truly comment‑free code may be unattainable, reducing unnecessary annotations and revisiting code structure can make the code less of a “secret” and more maintainable.