code-documentation

Focus comments on rationale and design intent rather than restating what the code does. Document non-obvious behavior, complex logic, and API contracts to help maintainers understand your reasoning and the problems you solved.

Good docstrings explain purpose, parameters, return values, and edge cases without restating obvious code. Include examples for non-trivial behavior and highlight design decisions that aren't apparent from the function signature.

Add comments to explain why a design choice was made, clarify complex algorithms, document API contracts, and capture constraints or trade-offs. Avoid comments that merely repeat what the code obviously does or describe syntax.

Write self-explanatory code with clear naming first, then add comments only where intent isn't obvious. Keep comments tied to immutable facts—rationale and constraints—rather than implementation details that change with refactoring.

Anti-patterns include obvious comments restating syntax, outdated documentation that contradicts current code, vague explanations without context, and missing API documentation for public functions. These create noise instead of clarity.

Document public APIs with clear contracts: purpose, parameters, return types, exceptions, and usage examples. Explain design decisions and constraints so consumers understand when and how to use each endpoint or function.