Why Every Good Code Needs Thoughtful Comments: 9 Proven Types

When the topic of code comments arises, many claim that good code should be self‑explanatory and not need comments, while others point to numerous high‑quality open‑source projects that include extensive annotations. The author argues that comments are beneficial in all cases, regardless of code quality.

Antirez, the creator of Redis, categorises comments into nine types. The first six are recommended, while the last three should be avoided.

1. Function Comment

Placed at the top of a function or a logical block, it serves as an inline API document, allowing readers to understand the purpose without diving into the implementation. This is especially useful for complex algorithms where the internal logic is hard to grasp.

2. Design Comment

Usually located at the beginning of a file, it explains the overall design decisions, algorithms used, and the rationale behind them, helping readers understand the higher‑level intent of the code.

3. Why Comment

Describes why a particular piece of code exists, offering insight into business context or special cases that are not obvious from the code alone.

4. Teacher Comment

Educational annotations that guide readers through the code, often found in tutorials or explanatory articles, making complex concepts like hash maps easier to follow line by line.

5. Checklist Comment

Reminds developers of related modifications that must be made elsewhere, a pattern common in large codebases such as the Linux kernel.

6. Guide Comment

Acts like a README within the source, outlining required environments, dependencies, configuration steps, and how to run the project, thereby lowering the cognitive load for newcomers.

7. Trivial Comment

Unnecessary remarks on obvious code, e.g., annotating a simple increment operation: count++; // increment Such comments add noise without providing value.

8. Debt Comment

Technical‑debt markers such as TODO or FIXME that flag temporary solutions; they should be reviewed and resolved regularly.

9. Backup Comment

Comments that retain old code versions as a fallback. While sometimes convenient during rapid development, they should be removed once the new implementation stabilises.

Overall, the author believes that well‑commented code is friendlier to both original authors and future maintainers, especially when combined with AI‑assisted tools that can generate code from clear annotations.