> the only time it really matters is when something has gone catastrophically wrong
Or in other words, it matters most when it's most needed and the recovery process is glad to have them.
Think about the airline industry and how many times the causes of an accident have been found in the months-old maintenance records of an aircraft, or in an examination of pilot training from last year.
Now imagine throwing away all the information that could have led to finding a cause and putting in place mechanisms and practices to prevent a recurrence. This is how the software industry continues to stumble over the same problems that were known and described in the 70s.
I don’t think it’s _necessary_ when something goes wrong. I think it’s a sign of a process going wrong (which is just as likely as your commit message process going wrong). If you can’t work out why a piece of code looks the way it does or why it even exists, the fix isn’t better commit messages, it’s better code.
I want to be clear I’m not just being a curmudgeon here. There’s been interesting, old work in the OO world about capturing use cases more explicitly in your model. I think some work around micro front-ends is promising. Anything that lets you compose new work in a modular, clear, explicit way is very interesting. And I think that’s the path we should take as an industry, rather than running git blame to understand why a particular case in a switch statement exists. At the very least, everything useful in a commit message could be a comment in the code, but even that seems weak to me.
You're correct that ideally the code would reflect the understanding of the programmers and the business. I've definitely worked with codebases where it's nearly impossible to discover any but the most basic things about the business, and I appreciate better code. Still, even if the code is clear, it's clear about how things are now, but what about in the past? Can just looking at the differences between and now clarify why things changed, and why the code was changed the way it was? What's become sort of a mantra for me, "what problem were they trying to solve?" That's not often clear in the diffs.
The ‘why’ of all of your code at the macro level should be clear from the acceptance tests (which hopefully document the motivating use cases and aren’t just barren series of steps with enigmatic names). At the micro level it should be done with naming (it’s really good to have the strategy pattern here because you can explicitly capture policies as named things, and occasionally keep old ones around as a contrast) and comments or doc strings.
I don’t know why the industry has settled on the idea that we only talk about ‘why’ at diff time in external tools. Even if the tools and languages today aren’t ideal, I think it’s a worthwhile thought experiment to constantly ask yourself, how can we better capture this information and serve this workflow in one place?
For example, most codebases put everything in a series of functional siloes based on the architectural layering of the app. What would it take for a framework to make it easy to write code built around vertical _features_, all the code for each of which is co-located (including tests and documentation), and which integrate into the app via various hooks. There are obviously a million ways to poke holes in this idea but I think we’ve learned the lesson in the industry a thousand times over that functional siloes are bad from a team structure and work scheduling point of view. Perhaps that ought to also apply all the way down to the program text.
Ultimately I’m more intrigued than religious here, but I will maintain that it’s at least a code smell when someone has to care too much about commit messages.
Or in other words, it matters most when it's most needed and the recovery process is glad to have them.
Think about the airline industry and how many times the causes of an accident have been found in the months-old maintenance records of an aircraft, or in an examination of pilot training from last year.
Now imagine throwing away all the information that could have led to finding a cause and putting in place mechanisms and practices to prevent a recurrence. This is how the software industry continues to stumble over the same problems that were known and described in the 70s.