5 ms·

Interesting topic. From my experience Headline + Bullet Points are far quicker to convey useful information, in a form that is terse yet easy to read. For exam

Interesting topic. From my experience Headline + Bullet Points are far quicker to convey useful information, in a form that is terse yet easy to read. For example: ---------------- improve Buffer Cache Management & logging - change 'tryDrop()' to skip immediately, if lock unavailable - move BufferCache logging to a separate logger - attach BufferTrim.Unsuccessful -> Preemptive Flush of oldest buffers -------------------------------- Having worked in many codebases & internal docs, I've found narrative significantly less efficient to read & write. In commit messages, far too many developers skip almost any detail as to what they're changing & why -- the slowness of narrative formats may substantially contribute to this. In docs (Wiki etc), narrative encourages developers to ramble about minor technical details while omitting all high-level context. Headline + bullet-points bypass a lot of struggles with narrative by allowing a simple headline and then, well, cutting to the point. This also illustrates a informed personal preference -- studies find lowercase English words faster to scan/ comprehend. See: http://literatejava.com/git/how-to-write-a-good-git-commit-message/ http://literatejava.com/git/how-to-write-a-good-git-commit-m...

stinos 4y ago
I don't really have a problem with bullet points, conveying relevant information is after all the most important thing the message should do, but if that example is an actual one then it would raise some flags during review. Mainly because it's not super readable (mix of styles, super terse requires extra interpreting) but also because it mostly explains what has changed (most often unneeded information, as that should be clear from the diff) and not really why it is done that way (ok, the code might have comments, but still I expect the message to explain that). In my experience, using bullet points like this is correlated with this style of messages which just list 'I did x, y, and z' whereas a more narrative style, which can still go in bullet points, is correlated with easily digestable messages explaining properly the reasons for changes. Anecdotal of course.
- u801e 4y ago
  > it mostly explains what has changed (most often unneeded information, as that should be clear from the diff) and not really why it is done that way Ideally, commit messages should at least briefly explain what was changed (e.g., Add feature X, Fix bug Y) in addition to why it was done. When people look at git log output, they won't always show the associated diff for each log message. Also, when running git blame, they'll see the commit id and title, but not the entire change. That doesn't mean that one can't run other commands to see the associated diff, or even getting the overall branch diff from the commit ids recorded in the merge commit, but having that what was done in the commit message allows one get an understanding before looking into it in more detail.
  - stinos 4y ago
    Ideally, commit messages should at least briefly explain what was changed Yes, sorry didn't mention it explicitly, but that's normally what the first line of the commit message is for.
rendall 4y ago
> Headline + Bullet Points are far quicker to convey useful information Not sure why the quicker qualification, here. Your example follows the article's guidelines exactly. (Except, as a minor point, the initial character is upper-case). In fact, if each of the bullets were its own commit, this would be the default message of the squash-commit to master.
darkerside 4y ago
Just thinking out loud, but wouldn't this be best handled with separate commits for each of these atomic changes, with a merge commit describing the intent ins narrative form? Don't ask me if I practice what I pushed there
- twhitmore 4y ago
  Good question. The example message is adapted from a fast-moving innovation stream; it's an example of moving quickly and getting a lot of major work done. In a more mature area, pace of work could often be slower and commits more granular. Until it's necessary to refactor/ reengineer things -- then commits are often larger again. That's been my experience anyway, YMMV.
  - darkerside 4y ago
    Fair point. We should act appropriately for our context.
coldacid 4y ago
Bullet points are fine, but again the message should contain the context of the change and the "why" of it, not the what and how (that's what the diff shows).

stinos 4y ago

I don't really have a problem with bullet points, conveying relevant information is after all the most important thing the message should do, but if that example is an actual one then it would raise some flags during review. Mainly because it's not super readable (mix of styles, super terse requires extra interpreting) but also because it mostly explains what has changed (most often unneeded information, as that should be clear from the diff) and not really why it is done that way (ok, the code might have comments, but still I expect the message to explain that). In my experience, using bullet points like this is correlated with this style of messages which just list 'I did x, y, and z' whereas a more narrative style, which can still go in bullet points, is correlated with easily digestable messages explaining properly the reasons for changes. Anecdotal of course.

u801e 4y ago
> it mostly explains what has changed (most often unneeded information, as that should be clear from the diff) and not really why it is done that way Ideally, commit messages should at least briefly explain what was changed (e.g., Add feature X, Fix bug Y) in addition to why it was done. When people look at git log output, they won't always show the associated diff for each log message. Also, when running git blame, they'll see the commit id and title, but not the entire change. That doesn't mean that one can't run other commands to see the associated diff, or even getting the overall branch diff from the commit ids recorded in the merge commit, but having that what was done in the commit message allows one get an understanding before looking into it in more detail.
- stinos 4y ago
  Ideally, commit messages should at least briefly explain what was changed Yes, sorry didn't mention it explicitly, but that's normally what the first line of the commit message is for.

rendall 4y ago

> Headline + Bullet Points are far quicker to convey useful information Not sure why the quicker qualification, here. Your example follows the article's guidelines exactly. (Except, as a minor point, the initial character is upper-case). In fact, if each of the bullets were its own commit, this would be the default message of the squash-commit to master.

darkerside 4y ago

Just thinking out loud, but wouldn't this be best handled with separate commits for each of these atomic changes, with a merge commit describing the intent ins narrative form? Don't ask me if I practice what I pushed there

twhitmore 4y ago
Good question. The example message is adapted from a fast-moving innovation stream; it's an example of moving quickly and getting a lot of major work done. In a more mature area, pace of work could often be slower and commits more granular. Until it's necessary to refactor/ reengineer things -- then commits are often larger again. That's been my experience anyway, YMMV.
- darkerside 4y ago
  Fair point. We should act appropriately for our context.

coldacid 4y ago

Bullet points are fine, but again the message should contain the context of the change and the "why" of it, not the what and how (that's what the diff shows).