Hacker News new | ask | show | jobs
by marktd 3716 days ago
Nitpick with #16: I don't like when there is no "why" associated with a style rule. I'm speaking specifically to #3, "Capitalize the subject line". Why is this preferred to not capitalizing a subject line? Is there a reason, or is it an arbitrary decision (which would be fine - sometimes a style decision is, "We need a standard, and we chose this one." But I think the author of the style guide should explain that that's what they're doing).

But in general I liked the article. It's under-appreciated how helpful a good commit log is.
4 comments
jcrites 3716 days ago
Capitalize the commit message because ...

Sometimes commit message deserves to be moderately long, like a paragraph or more. If one did not reference a code review or issue tracker link, for example, the need would likely be common. Even with an issue tracker there's value in capturing a few sentences of detail and sometimes more in the commit.

By capitalizing the commit message, it is natural to extend it from a single sentence phrase to a paragraph with an introductory sentence. I think of commit messages as analogous to JavaDoc where the first sentence or first line is taken as the subject, or like a document with a heading. It would be silly for short commit messages not to use capitalization while long do. A capitalized message works as a short description of the intro to a paragraph. Generally. once you're writing more than a single standalone sentence, capitalize. In a permanent medium where it can be either one, also capitalize.

A capitalized sentence or sentence fragment works in many contexts, like within a document or email. It would be annoying to convert going back and forth. Lastly, commit messages can sometimes act as names or proper nouns, and capitalization reinforces that role. Capitalization looks better as project or item headers in an issue tracker, and so to the extent that commits follow items, it's nice to consistently capitalize.

Capitalize commit messages because when Git tools generate commit messages, they generate capitalized ones. (Be consistent.)

I grok not capitalizing IM or IRC or other chat conversations, though I do if I start writing messages longer than a sentence. For everything but IM, capitalization constitutes the norm and good professional style.

This rationale might not be entirely satisfying, because why does English have capitalization to begin with? That's a linguistic question I don't know the answer to. However, I do know that the norms that lead to sentence capitalization also apply to commit messages and code documentation Not capitalizing them feels like refusing to capitalize any other writing: a potential distraction from the content.

link
mbrock 3716 days ago
Most of my commits start with a component name prefix and a colon. I don't capitalize those. I still write literate English commit message bodies.
link
jcrites 3715 days ago
That sounds reasonable to me.

  foo: Add utf8 support
If the component name is conventionally written in lower case, because it's a technical term, then I think a comment written in this way counts as good style. I might choose to capitalize Foo myself, but I think foo is defensible in that context.
link
dkersten 3716 days ago
I use this template and find my commit messages are much more useful now:

    # If applied, this commit will...
    
    # Explain why this change is being made
    
    # Provide links to any relevant tickets, articles or other resources
link
indiv0 3716 days ago
I like to write my commits in the Angular conventional-changelog format [0].

In particular, it looks like this:

    <type>(<scope>): <subject>
    <BLANK LINE>
    <body>
    <BLANK LINE>
    <footer>
Where `<type>` is the type of change (e.g. `feat` for a feature or `docs` for doc updates), `<scope>` is the scope of a change, `<subject>` is the subject line, with the first letter uncapitalized, `<body>` being an explanation of the change in imperative, present tense, and the `<footer>` containing information about breaking changes and any issues the commit closes.

I like it because I find that adhering to this style lets me have a nice seat of easy to read commits which explain their purpose and scope clearly.

Also, it lets me use a tool like `clog-cli` [1] to generate pretty changelogs [2] automatically!

The only nitpick I have with this style is the fact that they recommend not capitalizing the first letter of the subject line. This means that, for example, in emails or when creating a PR, I have to capitalize the summary so that it looks correct. Minor, but annoying.

[0]: https://github.com/conventional-changelog/conventional-chang...

[1]: https://github.com/clog-tool/clog-cli

[2]: https://github.com/clog-tool/clog-cli/blob/master/changelog....

link
nerdponx 3716 days ago
Capitalizing the subject line makes commit logs much easier to read in my opinion. There's a reason we capitalize letters at the beginning of sentences
link
Grue3 3716 days ago
But it's not the beginning of a sentence. It's supposed to be a continuation of the implicit phrase "When applied this commit will ..." In which case capitalizing makes no sense.
link
rlpb 3716 days ago
> It's supposed to be a continuation of the implicit phrase "When applied this commit will ..."

No: it's supposed to be written in imperative form. For those of us who are not linguists, it's easiest to explain this as a continuation of that phrase. However, it isn't a continuation. It stands on its own.

link