technical-writing

Make the first sentence stand alone as the summary, state what the caller must know such as contracts, side effects, and thread-safety, and never restate the signature. Follow the language convention for the summary verb, and skip comments on getters, setters, and obvious constructors.

Structure it for the reviewer: why with the ticket link, a short list of what changed, how to review including where to start and how it was tested, how to release with migrations and flags, then risks and follow-ups. Omit anything the diff already shows.

Never apply them to code, identifiers, or chat replies to the user, which belong to a separate reply-style rule set. The rules target text people read, such as docs, comments, commit bodies, and error messages.

Delete marketing adjectives and LLM vocabulary like leverage, delve, and streamline, replace metaphors with literal phrases, and avoid rule-of-three padding and em-dash pile-ups. Run the self-lint checklist: split long sentences, activate passive voice, and use plain verbs.

Only what the code cannot say: intent, constraints, trade-offs, or a rejected simpler approach and why. If someone could write the comment from the code alone, delete it, and never put ticket references in code comments.