Skip to content

Code documentation guideline#

This document provides code documentation rules that should be enforced for new code.

General#

  • G-01: All comments are sentences. This is nice for consistency and pays off if there is at least one comment that has more than one sentence.
  • G-02: Document the intent if the name is ambiguous or leaves too much room for interpretation. Try to come up with a better name first.
  • G-03: Document limitations, panics, and safety concerns.
  • G-04: Provide high-level descriptions of complex algorithms.
  • G-05: Point out design decisions or applied algorithms / patterns (e.g., optimistic concurrency for ResourceVersion).
  • G-06: Answer non-minor justification or comprehension questions a reviewer / user might raise.

Data structures#

  • DS-01: Every public facing struct / field must be documented (-> doubles as OpenAPI documentation).
  • DS-02: Document units if this is not obvious from the name (ram vs. ram_mib).

Functions#

  • F-01: Every public function must be documented.
  • F-02: A developer must be able to use a function solely based on the documentation plus the function signature. If the developer has to read the body in order to figure a crucial thing out (e.g., how to use it correctly), the documentation is lacking and needs to be updated.
  • F-03: A private function may stay undocumented if there is no justified need for documentation (e.g., short/trivial functions).
  • F-04: Trait implementations should not duplicate the comments of the trait definitions, because the latter are authoritative. We also want to keep things DRY (maintenance). Implementations may use function documentation to point out case-specific details, limitations / violations.
  • F-05: Examples are good. Though, keep uses of rust example code short. Do not confuse the reader, be as concise as possible. Use additional regular tests if necessary.

Code within functions#

  • CF-01: Do not use multi-line comments.
  • CF-02: Split multiple semantic paragraphs in comments using an empty comment line.

Other remarks#

  • Consider documenting the high level architecture in an architecture.md.
  • It is possible to include external markdown files as documentation like this: #![doc = include_str!("README.md")]

See also (not normative but still useful)#