Refactor your prose as you would your code:
- prefer terser expressions where they do not obstruct readability
- remove duplication, for example, moving repeated phrasing from list items to the list’s preamble
- find ways to simplify expressions
Prefer the active mood. For example, prefer
Prefer the active mood.
The active mood is to be preferred.
Use words for numbers of things, e.g. “there are three ways to achieve this”, up to a hundred. Use numbers to refer to numbers themselves, e.g. “and adds 2 to the total”.
Use English place names. Thus Copenhagen not København; Milan not Milano, and Zurich not Zürich.
Using place names correctly in a foreign language is a mark of competence. Using them in English is showing off.
Only is a crucial qualifier in documentation. Place it beside what you intend to qualify.
The reader can usually resolve any ambiguity by eliminating unlikely interpretations. Not always. Placing only in the right place relieves her of this work.
- The function will only return 0 if an error occurs.
If an error occurs, the function will do nothing but return the result of 0. It won’t also set 0 as the value of a variable, write 0 to file…
Here only qualifies return.
- The function will return only 0 if an error occurs.
If an error occurs, the function returns nothing but a solitary zero. Otherwise it may return anything. (Including a zero.)
Here only qualifies 0.
- The function will return 0 only if an error occurs.
If an error occurs the function will return a zero. Otherwise it will return something else.
Here only qualifies if.