Code Quality And Documentation Audit
Definition
Check whether the code and documentation will be readable and maintainable under production pressure. Comments should explain nonobvious intent and interfaces, not repeat code.
Questions To Ask
- Does the code follow existing naming, formatting, and organization patterns?
- Are public interfaces documented with caller-relevant contracts?
- Are design notes recorded where future maintainers will find them?
- Are comments stale, duplicative, or implementation-contaminated?
- Are TODOs, debug logs, or temporary code still present?
Existing Project Comparison
- Compare changed files to neighboring conventions and docs.
- Inspect README files, API docs, comments, examples, changelogs, and design notes.
- Check for vague names, hard-to-describe code, stale docs, excessive comments, and missing comments on nonobvious behavior.
Suggestive Plan
- Review changed and high-risk files for readability.
- Check documentation against actual behavior.
- Find stale comments, TODOs, debug code, and misleading notes.
- Add or request concise interface and design-intent documentation.
- Update
PRODUCTION_READINESS.md.
Example
If a billing retry policy is only explained in a commit message, require a design note near the retry owner or in durable operations docs.
Vocabulary
- Interface comment: caller-facing contract and expectation.
- Design note: durable explanation of an important tradeoff.
- Stale comment: comment contradicting current behavior.
- Obvious code: code whose behavior and intent are easy to understand.
Expected Outcome
Produce a code quality and documentation audit with consistency issues, stale docs, TODO/debug findings, readability risks, and required updates.
1---2name: code-quality-documentation-audit3description: Audit code quality and documentation before production. Use when checking consistency, readability, interface comments, design notes, stale comments, TODOs, debug code, naming, and nonobvious implementation choices.4---56# Code Quality And Documentation Audit78## Definition910Check whether the code and documentation will be readable and maintainable under production pressure. Comments should explain nonobvious intent and interfaces, not repeat code.1112## Questions To Ask1314- Does the code follow existing naming, formatting, and organization patterns?15- Are public interfaces documented with caller-relevant contracts?16- Are design notes recorded where future maintainers will find them?17- Are comments stale, duplicative, or implementation-contaminated?18- Are TODOs, debug logs, or temporary code still present?1920## Existing Project Comparison2122- Compare changed files to neighboring conventions and docs.23- Inspect README files, API docs, comments, examples, changelogs, and design notes.24- Check for vague names, hard-to-describe code, stale docs, excessive comments, and missing comments on nonobvious behavior.2526## Suggestive Plan27281. Review changed and high-risk files for readability.292. Check documentation against actual behavior.303. Find stale comments, TODOs, debug code, and misleading notes.314. Add or request concise interface and design-intent documentation.325. Update `PRODUCTION_READINESS.md`.3334## Example3536If a billing retry policy is only explained in a commit message, require a design note near the retry owner or in durable operations docs.3738## Vocabulary3940- Interface comment: caller-facing contract and expectation.41- Design note: durable explanation of an important tradeoff.42- Stale comment: comment contradicting current behavior.43- Obvious code: code whose behavior and intent are easy to understand.4445## Expected Outcome4647Produce a code quality and documentation audit with consistency issues, stale docs, TODO/debug findings, readability risks, and required updates.
harsh817