3 ms·
How am I supposed to be aware of a commit message specifying the “why not” when reading the code later down the line? I could easily imagine somebody refactori
by thehappyfellow 2y ago
How am I supposed to be aware of a commit message specifying the “why not” when reading the code later down the line?
I could easily imagine somebody refactoring code to an obviously better version, finding out it doesn’t work for subtle reasons, running got blame and cursing the person who left that information in a commit message instead of a comment.
- kazinator 2y agoThat's a different kind of why not: about why we didn't do it in this seemingly obvious incorrect way, but had to do it in a more complicated correct way. If that obvious incorrect way happens to match what you're thinking of doing, then that kind of why-not documentation will help. Warning future developers not to make certain changes is indeed something that should go in a comment. We can make a short comment like, /* if you think you can rewrite this in a simpler way, read commit df037acb first */ There are unfortunate situations when things have to be changed in multiple places together; you must not forget all of them. That deserves comments. If you have an enumeration that has to pack into 3 bits, there should be a comment warning not to add more elements than eight without increasing the number of bits; especially if there is no compile time assertion for it.
- thehappyfellow 2y agoI think I get it better now but I’m still not finding why keeping the whole comment in a commit message is better than in the source code. If it’s in source, I don’t need a context switch to read it, I can improve it (e.g. if the wording was ambiguous), I can easily extend it without asking people to read commits X, Y and Z in order. What’s the advantage?