I sometimes struggle to decide whether to put an explanation in a commit message, in the docs (say in an ADR). I tend to save everything as docs because files are a more “universal” interface, so to speak. They’re in plain sight and harder to miss.
I guess the main advantages of Git history are that it’s (1) uneditable and (2) directly linked to a specific commit.
There's an additional aspect: whoever ends up reading the messages later might not even be aware that there is more information somewhere else.
That's why I prefer to keep any important information as close as possible, either in the commit message or as a comment in the source code, to make sure it's unmissable to anyone working on it later.
zahrevsky · · focus · HN ↗
I guess the main advantages of Git history are that it’s (1) uneditable and (2) directly linked to a specific commit.
mopsi · · focus · HN ↗
That's why I prefer to keep any important information as close as possible, either in the commit message or as a comment in the source code, to make sure it's unmissable to anyone working on it later.