A PRACTICAL NOTE · Formatting

How to apply this guide

Use voice for the explanation and the editor for function names, flags and syntax.

Start with

Say what the comment should explain, such as why a fallback exists or when a loop stops. Choose plain Dictation for the first version to avoid changes in technical meaning.

Check before you finish

Check that the comment explains a behavior or reason the code does not already show. Remove any unverified assumption created during rewriting.

Evidence to keep: Compare the source words with the formatted draft and make sure meaning, names, dates and commitments remain intact. This page’s key limit is: Use voice for the explanation and the editor for function names, flags and syntax.

Start here

Speech recognition is good at prose but may replace an identifier with a similar word. Keep code tokens out of the parts you expect to paste without correction.

Draft the intent aloud

Say what the comment should explain, such as why a fallback exists or when a loop stops. Choose plain Dictation for the first version to avoid changes in technical meaning.

Insert precise identifiers separately

Paste the reviewed prose into a comment. Copy the exact function or variable names from the code, and verify backticks or punctuation in the destination editor.

Read as a maintainer

Check that the comment explains a behavior or reason the code does not already show. Remove any unverified assumption created during rewriting.

Keep exploring