|
|
|
|
|
|
by temac
2020 days ago
|
|
|
3 years latter good commit messages are extremely useful, and most of the time very short ones and/or giant commits are mostly useless. I occasionally read back multiple pages commit message I wrote and wished I dumped even more info from my brain at the time. If you work on small and short projects, you can do pretty much anything though. Of course it can still be unreasonable, but that's quite like anything else. But if in doubt, I would say write more; because if you really track your time in a detailed way, you will see that the marginal additional time is often shorter than you feel. And it taking 1/3 of your time may even be justified in some cases (but maybe you should write some doc in another way then). And I would not be so sure about it not magically making you better though: it is sometimes extremely useful to just write things down, quite like it is useful to explain a bug to a rubber duck. |
|
|
But a lot of the time my work is a string of exploration and in-depth sizeable PoCs until something solid and worth documenting rigorously is born. I strongly feel that if I spend time writing up each change as a “green” atomic commit at earlier stages when things are routinely rewritten and rethought, I might never arrive at the latter stage in a satisfactory way.
During such intense work, commenting about my implementation is a radically smaller context jump for me than switching my mind into “commit mode”. This is likely individual: I tend to be overly perfectionist with commits, trying to never mix style and logic changes in one, to make sure a fully functional version of software can be built at any given point in history, etc.
From another angle, I think a lot can be achieved with other forms of documentation, which you mention and which should not be underused either. Of course, best is having your APIs, architecture and units properly documented. It is undeniably bad form to refer others or future yourself to comments, especially for why’s. However, it’s arguably even worse to direct them to commit messages (though in a team it could be an invaluable troubleshooting instrument, that is not the context I have in mind).
(I would never advocate “fat commit” approach to be applied to teamwork on larger projects. Just wouldn’t recommend taking commit count as an axiomatic measure applicable at all times.)