[afarrell]

The guarantee would be the same guarantee you get when you update a codebase: that you (and code reviewers) look at the nearby code and see if it still makes sense in the context of your change.

> if the code is changed, then that old commit is no longer associated with it

Right, this is my problem with putting “why” always only in the commit message: Sometimes the “why” is both durable and shouldn’t be buried by later commits. Suppose you refactor the code: you’ve put it in a new place or you add trailing commas or you replace positional args with keyword args. Now the most recent commit is the one that explains that transition. Code is a UI that a future engineer will use to understand the system. An important prose explanation is part of that UI and you might decide it should present itself as an affordance.

This is an exercise of technical-communication judgement: I’m proposing that you should ask, where the explanation should go. Should it be hidden for those looking through the history? Probably. Should it be clearly visible alongside the code? If it is important and durable.

[lugg]

... The answer to "why?" goes in the tests.

Use commits for an audit trail of ticket numbers, urls, and playing the blame game.

Use comments for expressing the inferred. // That which is not explicitly stated.