17.8 Review of Documentation and Comments

Go To Top

Return to Git and Review Workflow

Documentation and comments form part of the implementation Baseline. Reviewers should inspect them with the same discipline they apply to source files, scripts, IDL definitions, Configuration, and tests.

Reviewers should confirm that new or modified handwritten source files, scripts, IDL files, Configuration templates, Markdown files, and public interfaces follow the file header and inline documentation conventions defined in Section 7.10.

Reviewers should also confirm that committed documentation avoids:

1. Informal wording that weakens technical clarity.
2. Unexplained abbreviations or local shorthand.
3. Personal pronouns unless the Artifact explicitly permits them.
4. Passive voice where active voice would identify the responsible actor more clearly.
5. Personal notes that refer to an individual developer rather than the project Baseline.
6. Temporary comments that do not link to an open issue, risk, or decision.
7. Editing-history labels such as “new”, “old”, “final”, “final-final”, or “backup”.
8. Unresolved comments such as “fix later”, “temporary hack”, “not sure why this works”, or “come back to this”.
9. Machine-specific or developer-specific references, such as local paths, usernames, workstation names, or personal versions.

Reviewers should correct minor documentation issues when practical. They should request a revision when unclear writing affects traceability, reproducibility, reviewability, implementation meaning, or Evidence of acceptance.