> Go easy on the comments.
> If you do have to add a comment, make it short and on point.
I defined what easy meant numerically.
<claude> Match the comment density of FoundationDB, which is 12 to 14 percent of non-blank lines in `fdbserver`, `fdbclient` and `flow` at 7.3. </claude>
> only add comments if there's a big gotcha that is not clear from the code itself
<claude> Comment why the code does a thing, not what it does. </claude>
> Comments should show history of code changes or functionality, only comment on the current state (or not at all)
I call this the tenseless continuous-present voice.
<claude> Each sentence states what is currently true of the system. </claude>
<claude> This rules out past-tense edit narration, future or imperative planning, and aging temporal qualifiers such as “now” or “previously”. </claude>
<claude> A sentence that states a present truth stays correct as long as the code stays the same, and goes stale visibly the moment the code changes. </claude>