7 hours ago
- The author argues that code comments are essential for maintainability, contrary to the belief that self-documenting code is sufficient; comments explain *why* code exists and reduce cognitive load.
- Nine types of comments are identified from Redis source code: Function, Design, Why, Teacher, Checklist, Guide, Trivial, Debt, and Backup comments.
- Teacher comments teach domain knowledge (e.g., math, data structures) to expand readership, while Why comments explain rationale behind clear code actions.
- Guide comments, like those in Redis, lower cognitive load by providing structure and rhythm, though they risk becoming trivial if they restate the obvious.
- Debt comments (TODO/FIXME) signal technical debt but are inferior to design comments; Backup comments (commented-out code) are discouraged with version control.
- Writing good comments is harder than writing good code because it requires deeper understanding, writing skills, and serves as a tool for bug hunting and design validation.