Clean Code, Comments, and Documentation

Use this skill when writing, reviewing, or refactoring code that is non-trivial, public, risky, security-sensitive, performance-sensitive, or hard to understand.

Core Rule

Optimize for the next reader.

Prefer clearer code before adding comments. Use better names, smaller functions, stronger types, simpler control flow, and tests first. Add comments only when they preserve information that the code itself cannot clearly express.

First Make the Code Self-Explaining

Before writing a comment, check whether the code can be improved instead: