Types and Best Practices of Code Comments

When discussing whether code needs comments, many claim that good code is self‑explanatory. However, most successful open‑source projects include detailed comments, which greatly improve readability and maintenance.

There are several common scenarios: a colleague asks why a piece of code lacks comments, a sudden need for design documentation reveals missing comments, or you inherit a project and appreciate existing annotations.

According to "antirez", the creator of Redis, comments can be classified into nine types. The first six are recommended, while the last three should be avoided.

1. Function Comments – Placed at the top of a function to describe its purpose, allowing readers to treat the code as a black box. They act like inline API documentation and keep documentation synchronized with code.

2. Design Comments – Usually at the file header, explaining the overall algorithm or design rationale, helping readers grasp high‑level intent.

3. Why Comments – Explain the reason behind a particular implementation, especially when the code performs non‑obvious business logic.

4. Teacher Comments – Educational annotations that guide readers line‑by‑line, useful for teaching complex concepts such as HasMap implementation.

5. Checklist Comments – Reminders to update related parts of the code when making changes, common in large projects like the Linux kernel.

6. Guide Comments – Help readers navigate the codebase, similar to a README, reducing cognitive load.

7. Trivial Comments – Unnecessary remarks on obvious code, e.g., count++; // increment , which add noise without value.

8. Debt Comments – Mark technical debt such as TODO or FIXME , useful for tracking unfinished work but should be resolved promptly.

9. Backup Comments – Commented‑out old code versions; they clutter the source and should be removed once the new implementation is stable.

Overall, well‑commented code is friendlier to both the original author and future maintainers, especially with AI coding assistants that rely on clear documentation.