Hacker News Reader

Comment by zahrevsky | Hacker News Reader

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.

View on HN

I usually go for very brief commit messages, one-liners preferentially. I would just write something on the body when I feel it call for more detailed explanation or if the reason isn't too obvious. I started using plain markdown for the "why" for each project, status, changelog, bugs etc. Every change to the notes is a commit and git became an audit trail with all the dated, uneditable record of all the decisions and changes. Markdown files won it for me because they are the first thing I read when I get back to a project and also because of the ease of access to AI tools.

The caveat is that docs can go stale while commit messages can't, it forces you to be extra careful so to be sure that the files are being correctly updated, I took care of that with a simple script that checks all the notes.

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.

Reply on news.ycombinator.com