Chalk Code Comments — What Earns a Comment

Interpret MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, etc. per RFC 2119.

Two kinds of comment

An interface comment says what a caller needs in order to use the thing without reading its body. An implementation comment says what the code inside it doesn't already say. Their defaults are opposite, and everything below is about implementation comments unless it says otherwise.

• An interface comment on a public surface exists by default, and is judged on completeness. Parameters, return, errors, preconditions, units, ownership, thread-safety. A caller who has to read the body to find one of those has been failed.
• A non-public surface takes implementation rules whatever its markup — a kdoc on a private function still faces the triggers.

The readers

An implementation comment's reader is a competent developer on this project, arriving at this line in a year, mid-investigation of a different bug. They did not read the commit that added it, do not know a change happened here, and will read this line and the twenty around it — nothing else.

Simulate that reader before there's a comment on the screen, not after.