concise-comments

Topics in the source

• Concise comments & docstrings
• The test
• For / not for
• Limits (defaults; exceed only with a stated reason)
• Delete on sight
• The pass (/la:concise-comments)

Preflight: run la-doctor --plugin once per session before using any la- or dr- command; if it fails, stop and show the user its output. Prevention: follow these when writing. Cleanup: run the pass below when invoked as /la:concise-comments. Keep a comment only if a competent reader of THIS codebase couldn't infer it from the code and names. Otherwise delete it, or cut it to the one missing fact in one line. For: the non-obvious why (constraint, invariant, footgun, edge-case gotcha) and a one-line what on public APIs. Not for: design narrative, alternatives-considered, defending the approach, repro steps, byte-count walkthroughs, ticket history, or restating the code. Those go in the PR description, the issue, or a test. Inline comment: 1 line. Needing 3+ lines to justify a line of code → rename things or move the rationale out. Function/method docstring: 1-line summary; +≤3 lines only for genuinely subtle behaviour. Module docstring: ≤8 lines. Test docstring: 1 line, or none if the name says it. Section banner: ≤1 label line, no --- paragraphs. Say it once at the definition; don't re-explain at every call site. Restates the code (# strip prefix above x.split(...)). Ticket-ID noise

This is an excerpt. Refer to the complete source and its current requirements.