Purpose-Driven Documentation

When adding or modifying code, ensure comments/doc comments are written to explain meaning and rationale—not just what the code does or where it’s mutated.

Apply this checklist:

• Explain “what” and “why”: If behavior becomes more complex or non-obvious, update the associated doc comment to state the rationale (what problem it solves / why complexity changed).
• Document invariants & ownership: For fields/state, clarify the field’s meaning and why it exists (e.g., derived/non-canonical vs canonical), and note any expected lifecycle (when it can be removed).
• Keep comments attached: Don’t insert unrelated items (e.g., #[cfg] helpers) between a doc comment and the item it documents; structure code so the comment clearly binds to the intended symbol.
• Avoid ambiguous references: In user-facing or accessibility text, use specific nouns (e.g., the actual tab name) rather than vague pronouns like “this tab.”
• Justify non-obvious decisions: For intentional exceptions or UI/logic branches, include short “why” comments to prevent future regressions.

Example (clarifying non-canonical state intent):

/// Current known statuses as reported to clients.
/// Not the canonical source of truth; once canonical indexing state is wired in,
/// this transitional cache should be removed.
codebase_index_statuses_by_repo: HashMap<String, RemoteCodebaseIndexStatus>,