17.8 Review of Documentation and Comments [Dido Solutions, Inc Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 17.8 Review of Documentation and Comments ======

[[fxdemo:05-part:start | Go To Top ]]

[[fxdemo:05-part:17-git-and-review-workflow:start | 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:

  - Informal wording that weakens technical clarity.
  - Unexplained abbreviations or local shorthand.
  - Personal pronouns unless the Artifact explicitly permits them.
  - Passive voice where active voice would identify the responsible actor more clearly.
  - Personal notes that refer to an individual developer rather than the project Baseline.
  - Temporary comments that do not link to an open issue, risk, or decision.
  - Editing-history labels such as "''new''", "''old''", "''final''", "''final-final''", or "''backup''".
  - Unresolved comments such as "''fix later''", "''temporary hack''", "''not sure why this works''", or "''come back to this''".
  - 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.

----

<WRAP centeralign>

© 2026 Dido Solutions, Inc. and Jackrabbit Consulting, Inc.

</WRAP>