docs(agents): require concise comments and docstrings

[jiwenc-nv]

Description

Comments in this tree have been drifting toward essays: multi-paragraph re-derivations of a decision, whole sentences in capitals, and running commentary on which earlier revision got what wrong. That is expensive to read and it goes stale, because it describes a process rather than the code.

The rule keeps what comments are actually for — a constraint, a measurement, a trap someone already paid for — and cuts the prose around it. The ceilings (~8 lines for a block, ~6 for a docstring) are rough rather than hard, because the occasional long note is worth it and the point is to make the author justify it to themselves. Longer explanations belong in a README.md or design doc a reader can skip, not inline where they cannot.

Applied to a ~5,400-line example currently under review (#900) it removed ~500 lines with no loss of any measured number, file reference or documented trap — app.py 1008 → 756 lines, one scene XML 234 → 128.

Split out of #900, where it was bundled by mistake: it is a repo-wide policy change and should not wait behind an example, nor land inside one.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Testing

Documentation only; no code paths touched. SKIP=check-copyright-year pre-commit run --all-files clean.

Checklist

• I have read and understood the contribution guidelines
• I have run the linter and formatter with SKIP=check-copyright-year pre-commit run --all-files
• I have made corresponding changes to the documentation
• I have added tests that prove my fix/feature works (or explained why not) — not applicable to a guidance document.
• I have signed off all my commits (git commit -s) per the DCO

Summary by CodeRabbit

• Documentation
  • Added guidance for writing concise, factual, and non-repetitive comments and documentation.
  • Clarified expectations for comments across source code, configuration, and scene files.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 30435e06-447e-47d7-8611-2fb4fd779f09

📥 Commits

Reviewing files that changed from the base of the PR and between 62f407d and 8d7b6d5.

📒 Files selected for processing (1)

• AGENTS.md

---

📝 Walkthrough

Walkthrough

AGENTS.md adds guidance for concise comments and docstrings. The guidance covers source comments, docstrings, configuration comments, and scene XML. It recommends documenting constraints and measured facts, avoiding historical narration and repetition, and moving long explanations to external documentation.

Estimated code review effort: 1 (Trivial) | ~2 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the repository guidance added for concise comments and docstrings.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch jiwenc/agents-concise-comments

---

_{Comment @coderabbitai help to get the list of available commands.}