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.




