documentation-standards

Code comments should explain why a decision was made, not what the code does. Focus on the rationale behind complex logic, trade-offs, and non-obvious choices. This approach accelerates code reviews and helps future developers understand intent without deciphering syntax.

A README should cover project purpose, setup instructions, usage examples, and contribution guidelines. Clear structure with these sections reduces onboarding time and prevents confusion about project scope, dependencies, and expected workflows.

Establish maintenance practices: update documentation during code review, mark sections with last-reviewed dates, and treat docs as first-class artifacts. Stale documentation misleads developers more than missing docs, so regular audits and updates prevent this costly problem.

Essential project documentation includes README for overview, ADRs for architectural decisions, ARCHITECTURE.md for system design, CHANGELOGs for version changes, and CONTRIBUTING guides for collaborators. This foundation ensures consistency across project phases and team transitions.

Verify that comments explain reasoning, breaking changes are documented in CHANGELOGs, ADRs exist for significant decisions, and the README reflects new features or API changes. Complete reviews catch undocumented impacts that create friction for future maintainers.

Inline comments explain localized reasoning and trade-offs within functions; project docs cover architecture, setup, and workflows. Together they create a complete knowledge base—comments answer why specific code exists, while project docs answer how systems fit together.