Hacker News Reader

Comment by BillinghamJ | Hacker News Reader

Does anyone actually care whether commit messages contain a period or not? If they're lower case, title case, sentence case, it's completely irrelevant

View on HN

Sadly. In my view they're bikeshedding, hard.

For those who don't know what that means https://en.wikipedia.org/wiki/Parkinson's_law_of_triviality

See also http://bikeshed.org/

(make sure to hit F5 a few times)

I am glad to see your comment. I wanted to post 'Who cares?' Not about commit messages, because having nice compact descriptive messages can be useful, but mostly about the 'dot' at the end. Because seriously; 'Who cares?'

Bikeshedding like this is useful as a team efficiency metric.

If you can't get quickly to an agreement about such a thing, or if the members of the team that didn't get their way actively rebel (or worse sabotage), you are working with a team of divas.

(note: of course developers whinge, as long as you stick with the team decisions once their are made, whinge all you want)

> If you can't get quickly to an agreement about such a thing ... you are working with a team of divas.

Or you're working on such a trivial problem that it should have been given to an individual, not a team.

Well that's the point. Feed the team with a trivial problem to see how they react.

A well working team will probably do as you say - volunteer an individual to write the rule in an email and follow it from there on.

If you going to introduce changes in a team, like for example introducing Agile (the proper way) or you are starting a new project, you want to quickly gauge the team dynamic, and that's a good exercise.

I feel like if you work in a team of divas you don't need a test like this to tell you that.

It kinda reminds me of that buzzfeed article "53 Signs Your Boyfriend Is Really Three Children In A Trenchcoat".

What is it about our industry (or perhaps just the slice of it that hangs around HN) that makes people feel the need to spout absolutist dogma about trivial shit like whether a commit message should be a sentence or not? Jesus. Sometimes a sentence is the most useful and sometimes a very short newspaper-headline-style summary is the most useful. Why must we constantly go in search of hard rules that prevent this sort of consideration? If having to shift between styles makes commit logs too hard to read for you, maybe the commit messages aren't the problem.

The only thing I care about is whether there's an empty line between the head and body of the (Git) commit message.

I don't care whether the lines are too long, whether they're nicely capitalized, whether they end with a dot. These are all things that tickle my OCD gland but I've learned to ignore them because it is ultimately useless and a waste of my time to get worked up about it. If the summary and description are good enough, I'm a happy man.

(I'm talking about reading others people's commit messages here. I try to make my own commit messages adhere to the scriptures as declared by his Holiness himself: https://gist.github.com/matthewhudson/1475276 (which, I now note, makes no mention of the length of the header line).)

I find it a lot easier to read a commit log when it's consistent in style.

Regardless of whether commit messages are in past or present tense, have trailing period or not, properly capitalized or not -- they are all equally unreadable with all the "Merge pull request #20552 from jamesdabbs/belongs-to-polymorphic-force-reload" junk.

Yeah, that's something that I never understood. The most important information is not that this is a merge, but the intent of the branch. You can give extra detail in the extended part, but the title should not be just referencing the way in which those changes found their way to the branch, and not what they do as in the rest of commits...

I believe Github lets one add extended commit messages for merge commits. Most of us (including me) tend to ignore that and use the autogenerated one. It'd be nice if we had an easy option to automatically include the PR's description (first comment) as the merge commit's message.

`git log --no-merges` saved me a lot of headaches after switching to a pull request-based review model at work.

My main point is not about dots but the way you change the content of the first line depending on how do you look at it.

The problem is that if your repo maintainer is encouraging you to use a title as a commit message it implies a different level of information content. commit -m "Features Aboundin: A new wave" vs. commit -m "Added initial project structure for new wave feature."

I'll hesitantly admit that I do, but not enough to blog about it. It's an unconscious indicator for me of inexperience with working with conventional Git, and very (very) often I have to intentionally ignore it for someone's benefit. However, that attitude is rooted in thinking about someone's teamwork abilities; good commit message etiquette, whether regarding periods, conventions on length and formatting, and squashing instead of merging seventeen of your test commits off a feature branch, or just general writing ability and effective communication, are all something I look for in a person.

I care more about merge commits, to be honest.

I wouldn't call this indicator so unconscious when the triggers can be so easily enumerated. Agreed wholeheartedly.

It's not LITERALLY about the period. It's about how content that contains periods tends to be written a certain way that the author doesn't care for in commit messages.

Did you really not understand that?

"Please don't use uppercase for emphasis. If you want to emphasize a word or phrase, put asterisks around it and it will get italicized."

https://news.ycombinator.com/newsguidelines.html

I didn't know that so I'm going to test it here.

Just don't ask me how to get a literal asterisk in there.

Haha! :D

Could HN's post and reply forms be changed so that if you type a word in uppercase in it, that message appears beside/under the form?

Considering there are people who have heart attacks based on whether a file ends with a newline or not, commit message formatting is a hugely important topic.

That's because there's some unix commandline tools that won't work right when a file does not end with a newline.

For serious. For just one example, `cat` doesn't act as expected without a trailing newline. You end up with stuff like <(echo) to space things out and it's really bogus.

lol. You'd think if "it's open source you can fix it yourself" worked as an ideology, its heartland would be Unix commandline text processing tools.

> "If it's open source you can fix it yourself, given that it is not standardised somehow, and that you have time to spare, and that you have the skills and knowhow to do it or that you possess the financial resources to hire some developers to do it for you.

FTFY.

Actually the ISO C99 language standard requires that every source file ends with a newline (§5.1.1.2, 2.):

"A source file that is not empty shall end in a new-line character [...]"

So if your C implementation doesn't complain about source files that don't end with a newline, you're unknowingly relying on a language extension.

Well his argument is not really the dot at the end, but rather whether the first line of the commit message is a title to the rest of it or whether it is a one-sentence synopsis of the changeset. Examples respectively:

  Fix layout.

  Replace proprietary grid layout w/ that of Bootstrap,
  so that it is easier to manage and use. [...]

  Substitute Bootstrap for proprietary grid.

  The proprietary grid system was abandoned for Bootstrap,
  as it will let us focus on the more peculiar stuff of the
  UI.

What? How can you not care.

Commit messages are extremely important when trying to understand the evolution of code. And the style matters a lot, not only the content. The (Linux) style is optimised both for people and tools (e.g. grep, awk).

When reviewing code I held the commit message at a much higher standard that the code itself. Nobody passes through me with a non-perfect commit. Luckily, people quickly learn and they start writing good messages without having me to force them, because they see the value.

Does having a dot at the end or not affect your understanding?

It does affect readability! That's the reason we have punctuation rules in human languages.

Maybe it doesn't have any effect when reviewing _one_ commit message, but when you're reading a list of hundreds, or thousands of them, it does have a huge impact.

This messages are meant to be consumed by humans, as in natural language. So it should respect the rules / conventions of that natural language.

The same way when we write code we should respect the coding style of the code base we are working on, we should respect the style conventions of the natural languages. Because of the same reasons.

Its defensible to adopt an abbreviated style suitable for the context of oneliner commits in a long report. Nobody uses natural language when creating other textual reports like that - e.g. log messages, checkbook register, ships' log. They all have an encoded style unrelated to natural language.

Also, even if it doesn't affect you, that is completely irrelevant for the project. A project should be oblivious to any one developer's preferences. Successful software projects thrive on conventions that affect the whole project. People do what's implicitly or explicitly agreed on, a person can't just ignore rules he doesn't see the value of.

People generally accept that when it's about coding conventions. Commit messages are just another convention. The rules are not arbitrary, in fact, if you read the Linux commit style guide, it will try to explain the value of the conventions.

If you still don't get it, or you disagree, too bad. Conventions are much more important that individual opinions. If you prefer spaces, you'd better start using tabs when you want to contribute to the Linux kernel.

(By you I meant, of course, some abstract person who doesn't see the value of certain rules, not kolme who I am responding to).

A project can't be completely oblivious to preferences. You'll never find something that everyone agrees on. Eventually you have to pick something that's acceptable to the majority of the people working on the project and move on.

Of course in the case of projects a developer is working on solo, they're free to do whatever they want ;) When I'm working with others, I still express my own preferences, but I'm willing to go along with whatever the group consensus is because I'd rather be consistent above anything else.

I've never seen a project use commit messages with periods and I've never felt like it affected readability at all. I don't think it really has anything to do with natural language style conventions. Writing a paragraph consisting of several sentences is very different from a disjoint set of statements which I have always seen separated by newlines anyway.

A lot of the people commenting on the article seem to be pretty adamant that something like this matters. Personally, I've never been confused by a period (or lack of thereof) at the end of a commit message. And if such a time comes, I'll give serious thought to whether it's worth anyone's time to teach the team to use/not use periods or whether I'm better off investing that time to teach them something more useful.

Well, commit logs could be good complement to developer documentation, if done properly. e.g. "See <some hash range> to see how to add a new protocol to Spyne!" "See <some hash range> to see how a new statement could be added to CPython!."

But, yes, if you care this much about commit format, put structured data in commit logs using yaml or something and be done with it :)

Possibly if there were going to be a machine parsing them, but otherwise no.

Reply on news.ycombinator.com