document

Rationale-focused JSDoc comments explain non-obvious design constraints and trade-offs rather than trivial code behavior. They colocate context with the codebase to document the why behind decisions, keeping explanations concise and intent-driven for edge cases.

The best way to document coding standards in a README is to emphasize design rationale, trade-offs, and non-obvious decisions. Co-locating README notes with the codebase ensures context stays current and concise, focusing on why choices were made.

Inline comments should be used to explain intent and edge cases when the design rationale is non-obvious. They guide developers through non-trivial decisions and constraints, maintaining a concise tone that avoids describing obvious code behavior.

Yes, rationale-first documentation works for existing codebases by reviewing the code and adding concise explanations for non-obvious decisions. It captures design constraints and trade-offs that were previously undocumented, applying documentation standards to colocate context with the code.

Documentation becomes outdated when it is separated from the codebase rather than co-located. Co-locating JSDocs and README notes with the code ensures context stays current, reducing the friction of updating rationale-focused explanations during software development.

Documenting what code does describes trivial behavior, while documenting why captures design rationale, trade-offs, and non-obvious constraints. Rationale-first documentation focuses on the why, providing context for edge cases and intent rather than restating implementation details.