Extensive Source Comments or Extensive Commit Messages?
written on Sunday, April 19, 2015
If you consider yourself as a serious developer, you know writing good commit messages is important. You don't want to be that guy:
This applies to source comments as well: good comments save time, bad comments can be worse than no comments.
For a long time, I usually favored source comments over commit messages: whenever I was about to commit a change which needed some explanations, I would often start to write a long commit message, then pause, go back to the code, write my long explanation as a comment and then commit the changes with a short message. After all, we are told we should not repeat ourselves.
Recently I was listening to Thom Parkin talking about rebasing on Git Minutes #33 (Git Minutes is a great podcast BTW, highly recommended) and he said this: "Commits tell a story". That made me realize one thing: we developers read code a lot, but we also read a lot of commit histories, either when tracking a bug or when reviewing a patchset. Reading code and reading history can be perceived as two different views of a project, and we should strive to make sure both views are readable. Our readers (which often are our future selves...) will thank us. It may require duplicating information from time to time, but that is a reasonable trade-off in my opinion.
So, "Write extensive source comments or extensive commit messages?" I'd say: "Do both".