documentation-standardslisted

# Documentation Standards **Purpose**: Defines the non-negotiable standards for code comments, docstrings, and global artifacts. ## 1. Red Flags (Anti-Rationalization) **STOP if you are thinking:** - "I'll add comments later" -> **WRONG**. Undocumented code is technical debt from the moment it is written. - "The code is self-documenting" -> **WRONG**. Code explains *how*; comments explain *why*. - "Artifacts are optional, I can skip them entirely" -> **WRONG**. Artifacts are part of delivery quality; `.AGENTS.md` must follow project memory policy. - "I'll put the full explanation in the table cell" -> **WRONG**. A table is a scanning device. Prose inside a cell destroys scanning and makes every row of that table churn on any edit. Cell = label; explanation goes below the table. - "It's all one topic, so it's one paragraph" -> **WRONG**. Topic is not structure. A reader needs entry points: paragraphs, lists, headings. A 30-line block has none. - "Line length doesn't matter, editors soft-wrap" -> **WRONG**. `git diff` and review comments are line-granular. A 2000-character line means a one-word fix shows up as a whole-paragraph rewrite, and reviewers stop reading. ## 2. Docstrings & JSDoc All classes and functions MUST have documentation. ### Python Use Google-style docstrings. > [!TIP] > See `assets/templates/python_docstring.py` for the format. ### JavaScript / TypeScript Use JSDoc standards. > [!TIP] > See `assets/templates/jsdoc_template.ts` for the format.