Documentation
¶
Overview ¶
Command commentdrift is an advisory, edit-time nudge against comment drift: it flags Go functions whose BODY changed in the staged diff while their doc comment — one that makes a CHECKABLE claim (always / never / sorted / deterministic / X before Y / …) — did NOT. The moment a maintainer edits a function is when they can still confirm the comment holds; catching drift here is far cheaper than rediscovering it during a later bug hunt.
It is deliberately a NUDGE, not a gate. It cannot know whether a comment is correct, only that code moved under an unchanged assertion, so by default it prints its findings and exits 0. Set COMMENTDRIFT_STRICT=1 to make it exit non-zero (e.g. to wire a hard check once the signal is trusted). It compares the staged index against HEAD, so it is meant to run from a pre-commit hook (`make hooks`). The discipline it embodies — comment the WHY, pin the WHAT with a test — lives in the repo CLAUDE.md.
Source Files