For commit messages and other technical writing, I use a "narrative coherence" checklist to help ensure that a change is clear and understandable:
- Establish a single thesis an external reviewer could recover from the diff.
- Unify vocabulary across code, comments, tests, and commit message.
- Use the same vocabulary consistently to refer to the same concepts.
- Keep every hunk that serves the thesis; consider the removal or deferral of the rest.
- Introduce abstractions at the point of need.
- Align tests to narrate the same story as the implementation.
- Reconcile the commit message and the diff.
- Order changes expositorily, not chronologically.
- Explain what the change does and why. Do not explain the details of the development process.
- Prefer to edit subtractively.
- Recompile and run all relevant tests after edits.
felipeerias · · focus · HN ↗
- Establish a single thesis an external reviewer could recover from the diff.
- Unify vocabulary across code, comments, tests, and commit message.
- Use the same vocabulary consistently to refer to the same concepts.
- Keep every hunk that serves the thesis; consider the removal or deferral of the rest.
- Introduce abstractions at the point of need.
- Align tests to narrate the same story as the implementation.
- Reconcile the commit message and the diff.
- Order changes expositorily, not chronologically.
- Explain what the change does and why. Do not explain the details of the development process.
- Prefer to edit subtractively.
- Recompile and run all relevant tests after edits.
- Iterate.
dormo · · focus · HN ↗
felipeerias · · focus · HN ↗