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).