| ▲ | felipeerias 8 hours ago | |
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. - Iterate. | ||
| ▲ | dormo 8 hours ago | parent [-] | |
That checklist sounds like at least as much work as writing a commit message. | ||