7.10 File Headers and Inline Documentation

Go To Top

Return to Naming and File Conventions

The team should consistently document handwritten Artifacts. File headers and inline documentation help developers and reviewers understand why an Artifact exists, how it participates in Phase 0, and whether it is handwritten, generated, or Configuration-driven.

Every handwritten source file and script should include a short header that identifies the Artifact’s purpose, its role in the Phase 0 Baseline, and any important usage constraints. Generated files should include a generated-file warning where the generator or file format permits it.

Language-specific documentation conventions should follow the normal practice of the language or file type:

1. Java source should use Javadoc for public classes and methods.
2. Python source should use module, class, and function docstrings.
3. JavaScript source should use JSDoc for public interfaces.
4. TypeScript source should use TSDoc or JSDoc for public interfaces.
5. Bash scripts should use a script header block and short comments before non-trivial functions.
6. IDL files should use comment blocks to explain structures, fields, and topic-facing types.
7. YAML, XML, and other Configuration files should use header comments where the format permits comments.
8. Markdown files should begin with a clear title and a short purpose statement.

Documentation should explain purpose, assumptions, inputs, outputs, Lifecycle effects, exceptions, exit codes, generated status, and Configuration dependencies where those details matter. Documentation should not repeat obvious code. The goal is to make the implementation reviewable and maintainable, not to create noise.