Do all the things like ++ or -- rants, post your own rants, comment on others' rants and build your customized dev avatarSign Up
VaderNT167310dI pity the poor sap who'll read those commit messages one day, in a desperate attempt to find out what the changes were good for. 🙁
Controversial opinion: Commit messages are overrated.
I know everyone preaches about descriptive commit messages, and I tend to put in some effort... But still.
I work a lot on bug hunting, performance tuning, detective work... And when something suspicious turns up I tend to just check the history for a method, and rewind through the commits using hotkeys in my IDE.
I don't read the commit messages, I flick rapidly through the history of the code to spot what I'm looking for.
Commit messages also lie no matter how much effort you put in: It's easy to forget about a small change, or make a typo, or you thought you made something work when you didn't.
The diff for a section of code is honest and absolute, the commit message is a flawed human label.
It's the same with comments: I prefer readable code over richly commented code as much as I prefer sensible commits at the right intervals over dutifully written commit messages.
What vs why.
I'm dealing so much with legacy code, it might as well become my middle name. What I find is there's always three questions involved:
Cryptic exceptions aside, code is clear about how it does... something. Great code is also clear about what this something is (or is supposed to be).
In a similar way, a diff tells you how code changed. Carefully crafted commits also tell you what changed on a higher level. How all changes in a commit connect together.
Neither code nor commits alone can tell you what they're good for. Why they exist. Why this variant over alternatives? Why this library? Why this change? This is what belongs in comments and commit messages. This is the information that helps me understand the history of a legacy project, and decide between mistake and intended quirk.
Overrated? No, crucial!