A commit message should answer the question "why?".
In the article they ask "Which would you rather read?"
I would prefer to read the first commit message they offer as an example:
"Re-adding ConfigurationPostProcessorTests after its brief removal in r814. @Ignore-ing the testCglibClassesAreLoadedJustInTimeForEnhancement() method as it turns out this was one of the culprits in the recent build breakage. The classloader hacking causes subtle downstream effects, breaking unrelated tests. The test method is still useful, but should only be run on a manual basis to ensure CGLIB is not prematurely classloaded, and should not be run as part of the automated build."
That is informative and gives me the information that I need. It answers the question "why?". And yet, this commit message is held up for criticism. And then, this is given as a recent example:
"Rework @PropertySource early parsing logic"
I have no idea what happened in that commit. And this commit does not answer the question of "why?".
I disagree with this entire article. The examples of "bad" commits are the one's that I would want my co-workers to write. The example of "good" commits are the kind that would make me angry with my co-workers.
Verbose commit messages are not useful because they are verbose, but a commit message should answer the question "why". Commit messages that answer the question "why" tend to be a bit longer than commit messages that fail to answer that question. I would much rather read a verbose message that answers the question of "why?" than I would read a short message that fails to answer that question.
Agreed -- when I read the article, I found the first set of commits more valuable than the second. Having short commits is better than long commits, but not at the expense of information. I don't need commits that use the words "updated, fixed, added" -- if I'm looking at `blame` I know something was updated/fixed/added. What matters is how something was changed, and sometimes why it was changed.
Write commits that help your coworkers figure out why the code looks the way it does. If you're writing "update FooBarFactory to fix Bug4" you're essentially wasting my time by using git to narrate the obvious.
In the article they ask "Which would you rather read?"
I would prefer to read the first commit message they offer as an example:
"Re-adding ConfigurationPostProcessorTests after its brief removal in r814. @Ignore-ing the testCglibClassesAreLoadedJustInTimeForEnhancement() method as it turns out this was one of the culprits in the recent build breakage. The classloader hacking causes subtle downstream effects, breaking unrelated tests. The test method is still useful, but should only be run on a manual basis to ensure CGLIB is not prematurely classloaded, and should not be run as part of the automated build."
That is informative and gives me the information that I need. It answers the question "why?". And yet, this commit message is held up for criticism. And then, this is given as a recent example:
"Rework @PropertySource early parsing logic"
I have no idea what happened in that commit. And this commit does not answer the question of "why?".
I disagree with this entire article. The examples of "bad" commits are the one's that I would want my co-workers to write. The example of "good" commits are the kind that would make me angry with my co-workers.
Verbose commit messages are not useful because they are verbose, but a commit message should answer the question "why". Commit messages that answer the question "why" tend to be a bit longer than commit messages that fail to answer that question. I would much rather read a verbose message that answers the question of "why?" than I would read a short message that fails to answer that question.