How many of you struggle to write good commit messages? A recent post on writing commit messages like a pro had me thinking about all of the articles and how-to guides that I've seen that purport to give you some byte-sized tips and tricks that will suddenly make you a Better Developer™.

I don't hate them, of course. I know that they're all coming from a place of good intentions and the desire for all of us to become better, more effective developers.

There's only one problem.

If there were a simple trick that would suddenly make us better developers then ML could do our jobs (And yes, there is a category of developers that can be replaced by ML).

But the fact of the matter is that Software Development was never about the what and it's always about the why. Everything that you struggle with on a daily basis, everything you wish was different, anything you would like to improve will always have a why behind it, and the only way to really and truly improve as a developer is to enhance your ability to understand the why.

• Poor commit messages are poor because they lack the reasons /why/ you made the change. We just have to look at the diff to know what you changed.
• Poor bug reports are usually created because the author fails to understand why they need to be clear and provide step-by-step instructions
• Poor email communication is usually because the "why's" are never answered.
• Time wasting meetings are because there's a lack of a clear and agreed upon why you're meeting.
• You struggle to understand what broke in this code because you don't know why things are happening that way.

There isn't a simple shortcut to make any of this better, of course. But there is one weird trick that you can apply, and that is to accept and adopt the following phrase:

There must be a reason!

Computers excel at doing exactly what they're told, regardless of what we meant. Including preserving copies of data forever. But they're terrible at being able to infer things like motivation and actually reason. So if we want to continue to improve as developers, we need to do our very best to capture the reasons that things happened.

When writing a git commit message, just think of it like an email from you, to everyone everywhere, all at once.

Subject: Fixed the frobnosticator

I had a conversation with Alice in accounting, and she showed me how the frobnosticator would incorrectly reticulate the splines. It took me a while, but Bob helped me figure out that in 1992 there was a colleague who's name has been lost to the annals of history, who worked 1-1 with Steve from accounting to produce the spline code, based on Rule 3, subsection 4 of the Space Based property owners association, 1973 edition.

As it turns out, when the moon is in the seventh house and Jupiter aligns with Mars, that's when the splines should have a left-handed spin. But there was an off-by-one error and it was happening when the moon was in the eighth house!

As it turned out, the only surviving copy of the 1973 edition was in the basement lavatory, behind a sign saying, "Beware of Leopard", but I verified that this new logic is now correct based on these standards.

But Here Be Dragons.

It is a bit miserable, because you have to switch gears -- no longer are you thinking, "What do I have to do to make this fix?" but, "What is the 'Why' behind all of these changes I made, and how do I communicate that effectively?"

And that's not a template that you can just fill out.

But the good news is that it's possible to do, and the more you practice, the better you'll get at it. So maybe it's not so weird, after all.