# Documentation and Comments

## Public API Documentation

- **Clear Usage**: For public interfaces, explain the intended usage clearly, with concise examples.
- **Public Classes**: Explain all public attributes.
- **Public Methods/Functions**: Explain all arguments, return values, and raised exceptions.

## Internal Implementation Comments

- **Explain Why, Not What**: For internal code and private methods, explain **why**, not **what** — the code itself should be self-documenting.
- **Stale References**: Don't reference RFCs or design docs in source code (they become stale).
