Before we begin if you are looking for any real tricks with
git, you should
probably checkout my dump of git
cheatsheet. The big challenge today’s
software developer faces is not about having to come up with his/her
implementation of a problem. That’s easy, not fast, but easy. The biggest
challenge a developer faces is to do with inheriting/understanding a
codebase. This typically entails looking at strange choices the original
developer made and, let’s face it, bitching about how bad the codebase is. Most
times, you are consciously aware that you, in all your wisdom and hackery, would
not have made a better choice. In fact, some times you are confident you would
have sucked in the situation that brought the orginal developer to make this
I think a majority of times, the issue arises from the fact that the original developer fails to convey their thoughts diligently. No matter how rich the documentation of a project is, the “feeling” of the developer while making the commit is never conveyed so intimately as the commit text.
So, here’s my “time machine” idea. Make the git commit text as rich and relevant as possible. This can be as crazy as you often find in the Linux Kernel or something more moderate as a 5-liner that succinctly describes all you need to know about the commit. In general, having a structure to the commit text always helps. It does not have to vex eloquent about the process through which the solution or “solution” was arrived at. It can simply have a predictable structure, something as follows might be worthwhile considering:
Structure of a Good Commit Text:
This is a one line summary of the commit text This is a paragraph describing the problem in simple present tense. It can describe why the issue exists, any history, any causal events, any triggers etc. can be described here. This is a paragraph describing the solution to the above problem in simple present tense. It should describe why this change is needed as clearly as possible. If there any strange implementation choices this is a good place to describe them. Do not complicate it, just put your throughts down in simple words. Don't be afraid to describe and log any thoughts about mini decisions made such as a choice of data structure, any choice to call a particular library function instead of implementing it (or vice versa). More details are acceptable here. This is a paragraph describes what you have tested and their results
Just doing this conveys more than enough info to the reader who does not have to switch to the documentation any more. In fact, now they should have a blow-by-blow account of the detailed history of the project. Of course, this may not be ideal to get the big picture or the overall design of the project. This is the stuff that comes after all that. A single, well written commit can actually save the reader several tens of hours of digging around the code base, debugging, or just get to a productive stage and help contribute to the project.
Best For The Last:
Git allows us to define a commit template that it will bring up each time you are making a new commit. Defining the structure within such a template can do most of the heavy lifting for you. It also prevents you from hitting the “Writer’s Block” since the structure of what needs to be added is already present. You need to define this template in ``~/.git-commit-template.txt
[commit] # file containing the commit text template template = ~/.gitmessage
One liner describing the change(<=50 chars) PROBLEM: Description of the problem goes here SOLUTION: Description of the solution goes here TESTS: Explain the how you tested the change. If possible also provide links where your working solution is hosted so that reviewer can test it. How you tested this change.
Of course, there are all sorts of other rigorous templates possible and even used in some of the projects. But I personally feel that this particular template hits the sweet spot of practical and useful. All my Linux Kernel Commits follow this pattern.
If you like topics such as this then please consider subscribing to my podcast. I talk to some of the stalwarts in tech and ask them what their favorite productivity hacks are:
Available on iTunes Podcast
Visit Void Star Podcast’s page on iTunes Podcast Portal. Please Click ‘Subscribe’, leave a comment.