Remix.run Logo
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.