For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /packs/languages/python/comments.md.
Quick start

Comments

Document the behavior a caller cannot learn from annotations alone.

Public contracts

Why

A Result annotation does not explain which failure literal is returned or whether the operation reads an external resource.

Rules

  • MUST document consequential public functions and capabilities with docstrings. [review]
  • MUST describe input constraints, return behavior, effects, and failure variants. [review]
  • MUST describe typed failure values rather than invent a Raises contract for an exception-free domain function. [review]
  • MUST explain any external exceptions converted by the adapter. [review]
  • MUST provide executable examples when the contract needs demonstration. [review]
  • MUST avoid comments that paraphrase the next statement. [review]
  • MUST record a safety reason when guarded use of a raising primitive is intended to be total. [review]

[review]

Configured docstring checks cover syntax and style. Tests and review establish example validity and contract completeness.

Enforcement

Configured docstring checks cover syntax and style. Tests and review establish example validity and contract completeness.