Mindlessly jogging in the web stream, I stumbled upon a post that pointed me to a good read detailing why ‘why’ matters more than ‘what’ in our Git commits.
TL;DR— the article explained extensively why ‘why’ matters more than ‘what’ since, “anyone can see WHAT you did just by looking at the code. But the code can never tell someone WHY you did it”, with an example Git commit going along the lines of “user should be able to see the card before editing it” despite the old way; “card view controller added”.
Albeit an enlightening read, it looked like it had missed few subtle annotations which could have drastically disrupted the way we would have typed our next Git commit. The author’s suggestion looked a little vague and it also sounded like something out of a User Requirement Document.
A commit speaks of a commitment of a developer to the project. It specifies a certain milestone and can be an addition or a change. Therefore, there can be instances ‘why’ doesn’t matter at all such as ‘added main template’ or even ‘added settings modal’ because they can be contextually insignificant during the resulting process. And also the little omission of ‘what’ wouldn’t work either since most of the times I look up on a commit is when I want to quickly know who did this change (isn’t that the whole point of it?) before asking why it happened. That’s what eye catches fast, ‘what’ of a commit before a ‘why’.
Therefore, as a solution to all, I propose combining both ‘what’ and ‘why’ for a better commit. A better way of saying the author’s example would be ‘added card view controller to enable user to view the card before editing’. With a single line, commit message talks about ‘what’ the dev has done and also ‘why’ he/she has done it. Easy, cleaner and straightforward than the default convention.
Happy Git-ing!
References- Gupta, S. (2017)- Writing Great Git Commit Messages.