I've worked with 5 different SCMs and I'm convinced that the reason why git repos often have such poor commit messages is because of the git commit style guide. So much of it only makes sense once you realize it's been optimized for like 5 of its original users reading it on 72 character terminal screens.
Asking people to fit a meaningful description of the change into 50 characters is silly, and it's IMO the reason why so many of them just write "fix bug" and call it a day.
This is, I believe, still the best guide out there. When I'm coaching juniors, I recommend this guide, over the opinionated and outdated git "best practices" and I think the results are much better.
That Google guide also says that the first line of the commit message should be a "short summary of what is being done". Is your complaint that 50/72 characters is too short? How long can it be before no longer meets the Google criteria, in your opinion?
Yeah, I specifically think 50 is too short. I am a big fan of brevity, but I think the sweet spot is somewhere around 100. Consider that all of these messages exceed the 50-character limit:
[startup] Don't drop uid until all controller fds are open
[bpf] Fix the exec exchange hitting verifier limit on Fedora
[controller] Optimize partial policy updates with delta
They're as short (IMO) as can be without omitting useful information, but git says they're all illegal by some margin.
I agree on the value of concise writing and dislike word salads, but if you're a junior engineer, then I have maybe 1 hour with you per week and I probably shouldn't spend that time being your English teacher.
I know I've seen some people recommend 50 (my guess is that's to make some room for metadata from commands like `git log --online` in an 80-column terminal?) but I've personally always capped all lines at 72, including the first. 100 seems like a reasonable limit too, but I probably wouldn't go above that.
> git says they're all illegal by some margin
Git will accept almost anything as a commit message. Is there a specific style guide you're referring to?
---
EDIT: Huh, I guess git does have an official recommendation. I'd never noticed this text in `git help commit`:
> Though not required, it's a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description.
I wouldn't feel bad about not following this advice. Even the author doesn't seem dogmatic about it.
> if you're a junior engineer, then I have maybe 1 hour with you per week and I probably shouldn't spend that time being your English teacher
It's not important enough to make a big deal out of, but if I see it over and over from the same person I might mention it during code review ("your commit messages are a bit wordy; for example instead of '…', consider '…'") or write down as part of a style guide (e.g. if we're tagging commits like in your examples, wherever we wrote down the rules for that). It's the same for other unimportant things that it's nice to agree on (e.g. capitalization of initialisms in code—is it `.toJson()` or `.toJSON()`?).
I may be misunderstanding: are you saying a commit message with a 200-character-long first line could be an example of a "good" message to you/Googlers? To me that seems like something that could almost certainly be summarized further, regardless of how complex the changeset is (if not it's a sign the commit should be broken up into multiple simpler commits).
Can you give me an example of a commit where the "short, focused summary" can only be usefully-expressed in 200+ characters?
A good dev isnt necessarily a good writer. Summarising complexity concisely is difficult.
Restrictions lead devs to write to useless messages like 'fixed a bug' rather than messages that are slightly verbose but actually useful.
Most messages wont be 200 chars. But id rather 200 chars of useful text than 72chars of useless text.
The real world is full of average devs that are average writers under time pressure to deliver code. Expecting them to deliver above average commit messages like googles examples is a pipe dream.
Should this reasoning be applied to other skills involved in software engineering? If someone never writes tests, or over-architects everything, or has terrible people skills, or never updates documentation, or doesn't bring attention to blockers, or constantly forgets to update the issue tracker, or doesn't follow the local code conventions, or works on random tasks and ignores high-priority ones, etc etc etc the solution isn't usually "don't ask them to do a thing they're bad at", it's "help them get better".
The important question is whether "skimmable commit messages" is a thing you care about enough to advocate for and teach people about. Maybe you don't, and that's fine.
> But id rather 200 chars of useful text than 72chars of useless text.
I completely agree with this. I just don't think those are the only two options.
> Expecting them to deliver above average commit messages like googles examples is a pipe dream.
This thread started with praise for that Google guide and I assumed you were of similar opinion given your reply. That's why I kept referring to it.
1. I basically agree with everything you say, I only think the limit should be ~50-100% higher. Not 10x, but 1.5-2x.
2. For some reason, concise writing is the hardest thing to teach and demand consistently. I think a part of is that people try to hide incompetence behind a word salad, but also I think non-native speakers use more words than they need. It gets to a point where you either have to become everyone's English teacher or accept some amount of word salad.
I think most projects limit commit message titles to 68-72 characters, not 50, which is indeed too little to say much of anything. I don't find it hard to write 70-character summaries, and as a maintainer, I find it very useful to have those available for skimming.
When I do maintainer work that involves skimming a list of dozens of commits for information, it's very helpful to have concise commit titles.
Asking people to fit a meaningful description of the change into 50 characters is silly, and it's IMO the reason why so many of them just write "fix bug" and call it a day.
Someone else has posted the Google guide for CL (change list) messages, but let me boost the signal: https://google.github.io/eng-practices/review/developer/cl-d...
This is, I believe, still the best guide out there. When I'm coaching juniors, I recommend this guide, over the opinionated and outdated git "best practices" and I think the results are much better.