You were almost certainly thinking "WHY is this like this?", not "What is a one-line summary of what happened in this commit?".
Most commit messages are next to useless because they focus on WHAT was done instead of WHY.
This is exactly the wrong thing to focus on.
You can always reconstruct what changes a commit contains, but it's near impossible to unearth the reason it was done.
(thread)
You were almost certainly thinking "WHY is this like this?", not "What is a one-line summary of what happened in this commit?".
```
[one line-summary of changes]
Because:
- [relevant context]
- [why you decided to change things]
- [reason you're doing it now]
This commit:
- [does X]
- [does Y]
- [does Z]
```
First, it captures context that will be near impossible to recover later. Trust me, this stuff is gold.
Secondly, if you train yourself to ask why you're making every change, you'll tend to make better changes.
The first time you see a commit message like the above instead of "refactor OrderWidget", you'll be a convert.
https://t.co/8e9p3x0zb0
https://t.co/KrOvHJPMXg
https://t.co/rnWpApDrTx
https://t.co/R7tAV3b8rx
More from Tech
I think about this a lot, both in IT and civil infrastructure. It looks so trivial to “fix” from the outside. In fact, it is incredibly draining to do the entirely crushing work of real policy changes internally. It’s harder than drafting a blank page of how the world should be.
I’m at a sort of career crisis point. In my job before, three people could contain the entire complexity of a nation-wide company’s IT infrastructure in their head.
Once you move above that mark, it becomes exponentially, far and away beyond anything I dreamed, more difficult.
And I look at candidates and know-everything’s who think it’s all so easy. Or, people who think we could burn it down with no losses and start over.
God I wish I lived in that world of triviality. In moments, I find myself regretting leaving that place of self-directed autonomy.
For ten years I knew I could build something and see results that same day. Now I’m adjusting to building something in my mind in one day, and it taking a year to do the due-diligence and edge cases and documentation and familiarization and roll-out.
That’s the hard work. It’s not technical. It’s not becoming a rockstar to peers.
These people look at me and just see another self-important idiot in Security who thinks they understand the system others live. Who thinks “bad” designs were made for no reason.
Who wasn’t there.
The tragedy of revolutionaries is they design a utopia by a river but discover the impure city they razed was on stilts for a reason.
— SwiftOnSecurity (@SwiftOnSecurity) June 19, 2016
I’m at a sort of career crisis point. In my job before, three people could contain the entire complexity of a nation-wide company’s IT infrastructure in their head.
Once you move above that mark, it becomes exponentially, far and away beyond anything I dreamed, more difficult.
And I look at candidates and know-everything’s who think it’s all so easy. Or, people who think we could burn it down with no losses and start over.
God I wish I lived in that world of triviality. In moments, I find myself regretting leaving that place of self-directed autonomy.
For ten years I knew I could build something and see results that same day. Now I’m adjusting to building something in my mind in one day, and it taking a year to do the due-diligence and edge cases and documentation and familiarization and roll-out.
That’s the hard work. It’s not technical. It’s not becoming a rockstar to peers.
These people look at me and just see another self-important idiot in Security who thinks they understand the system others live. Who thinks “bad” designs were made for no reason.
Who wasn’t there.
