On Commit Messages
who-t.blogspot.com
who-t.blogspot.com
Though it sounds like they're going to replace all this with Visual Studio Extra Crispy Team System for Epic Workgroups Prime. Best of luck prying everyone I met off vim and build.exe, guys.
Mind you - this was a guy with a few decades of experience.
True enough, but we never what he was claiming was done. It was just better.
Though I admit, yours is much worse...
I'm going to post a link to this at the top of our project's Trac page to remind everyone of the (a) right way to do it.
on the one hand, it seems efficient to put meta-data in the commit rather than clouding the code itself. on the other hand, i'm much more likely to go back to a piece of code and reread my comments and architectural diagrams then visit the repo logs. if documentation is too big or orthogonal to go in a class or function comment, then i put it in the docs folder.
it is true that writing a larger overview of, say, the thread timings is useful near the thread timing tests. i'm not above just putting a thread timing explanation in the docs folder though, especially if that influences much of the architecture and coding conventions elsewhere.
commit messages seem nice to look back on, but anything that impacts the current code state should be present in the current docs. otherwise new developers and maintainers have to look through a chronology of logs messages, which presents the same problem as blogs and hacker news compared to say wikipedia.
My approach is to use detailed descriptions in both places: commit logs track the evolution of the source tree, and comments/documentation describe the design and implementation of the source tree at a snapshot in time (e.g. now/tip).
when i reach that point where i start wanting to revert the repo or backtrack on changes then commit docs will make much more sense. i still leave a good commit message when i can but....documenting the now/tip in the code is far more useful to me currently.
Making detailed commit messages is "documenting the process". Making code documentation is documenting the product. The latter, in my opinion, is much more important.
The thing I am currently investigating is to commit extremely often during development and then use rebase to squash all of these extremely tiny changes into the actual change. Don't come with the "atomic single changes"-stick after me for squashing local commits, because when I said extremely tiny, I meant extremely tiny. Currently, I commit pretty much whenever a new test is red or the last red test is green, or after a single refactoring step. Given that, I end up with a very detailed sequence of steps and changes I made. Once you are done then, you can just add a summary line, a quick paragraph explaining the reason for those changes and reformat the previous commit messages into a (hieraichally structured) list of detailed changes.
I can just repeat this: Doing this is almost no noticeable overhead (it's just a git commit -a -m "Move method: Foo.bar -> Bar" after a successful build and some rebasing eventually, which takes 5 - 10 minutes after an hour or two of development) and massively improved my commit messages.