Marc Billow
7086b134c0
CONTRIBUTING.md gains a "Code comments" section: comment the why not the what, keep it to a sentence or two with a pointer to the load-bearing evidence, don't re-derive a sibling's already-documented reasoning, and move failed-attempt investigation logs out of inline comments. Applied that policy across the codebase: condensed sprawling module docstrings, per-entity essays, and multi-paragraph rationale blocks down to their load-bearing conclusions, while preserving the actual "why" (issue numbers, calibration evidence, gotchas, don't-guess rationale). No functional code changed — verified via diff review, ruff, ty, and the full pytest suite (1211 passed). One inline investigation log (the AC filter-reset "tried and failed" notes) moved to docs/investigations/ac-filter-reset.md rather than being deleted, per the new guideline on where that kind of record belongs.
3.0 KiB
3.0 KiB
Contributing
See the README's Contributing section for what kinds of patches are welcome and the PII rules for diagnostics/dumps in a PR. This file covers how changes get committed.
Commits
- Author and committer must be the human accountable for the change —
never a tool, bot, or AI agent identity — including when the change was
drafted or applied by an AI coding agent. Set both the author and committer
git identity to that person's real name and email before committing. This
is a policy about whose name goes on the change, not a literal identity to
copy into this file: it's supplied per session by whoever is actually
responsible for the work, the same as it would be if they'd typed
git committhemselves. - No co-author trailers for AI tools or assistants. Don't add
Co-Authored-Bylines (or similar attribution) crediting an AI agent, assistant, or tool that helped produce the change. The commit is attributed entirely to the accountable human.
Code comments
This codebase reverse-engineers undocumented device APIs, so comments recording why a decision was made (a calibration, a rejected write, an issue number a quirk was confirmed against) are genuinely valuable — more valuable than in most codebases. That's exactly why comments here need discipline: it's easy for "explain the reasoning" to slide into "narrate the whole investigation," and a file where every line has a paragraph under it is as hard to read as one with no comments at all. Keep the conclusion; cut the journey.
- Comment the "why," never the "what." If a comment just restates what the next line already says, delete it. Code should read clearly enough on its own that comments are only needed for the non-obvious.
- One or two sentences, not an essay. State the conclusion and the one piece of evidence that makes it credible (an issue number, a model name, a single confirming observation). Don't reproduce the full investigation — every dump checked, every attempt that failed, every hypothesis considered and discarded. A future reader needs to trust the conclusion and know where to look if they need to redo the work, not relive it.
- A pointer, not a re-derivation. Cite the issue/model once; don't
re-explain a sibling function's already-documented reasoning. Reference
it (
same reasoning as X above) instead of restating it. - Module/class docstrings are a short orientation, not a design doc. A few lines on purpose and any cross-cutting invariant is enough.
- Failed-attempt logs don't belong inline. If an investigation into an unsolved problem produced real negative results worth preserving (e.g. a reset mechanism nobody could find), put them in an issue or docs, not a block comment several times longer than the code it sits above.
- When in doubt, cut. If deleting a comment wouldn't lose real understanding, it's noise. Prefer trimming an existing comment over adding a new one.
For AI coding agents
See AGENTS.md.