6 ms·

I don’t completely agree. By taking the time to write commit messages you are documenting your code at a fine-grained level. Think of it like a short email that

I don’t completely agree. By taking the time to write commit messages you are documenting your code at a fine-grained level. Think of it like a short email that explains to your (future) colleagues and future self what you changed and especially why you did it. A good git log prevents unnecessary headaches and saves a lot of time. Typical situation: you just found a couple of lines whose purpose is not completely obvious. If the author is still there, you both waste time discussing. If she/he left the company and you have to figure it out by yourself. Now imagine using git log to identify when these lines where introduced/changed and getting an explanation as to why. So yeah, writing good commit messages can feel like a waste of time. Like writing good code can feel like a waste of time. You should not be doing it to please your colleague, but rather to contribute to a maintainable codebase. It’s worth the extra minutes here and there. Bonus point: less documentation to write.

lmilcin 7y ago
Nobody questions it is important to write clear commit messages. The issue is being nitpicky about what exact form is being used like whether to capitalize first letter or not. When I look at the repository I am happy if I can understand the messages at all. It's challenging to get people to group changes in a logical way so that the commit makes sense. I am not going to pick on somebody because he used wrong tense or did not capitalize first word of the message if the changes are grouped logically and the commit mentions the correct ticket and purpose of the commit.
- remilouf 7y ago
  I feel it reduces cognitive load, like proper formatting of code. Do you enforce consistent code formatting in your codebase (using CI, maybe)? If so, why wouldn’t you do that with commits?
  - bjourne 7y ago
    Because the commit messages, just like email messages, isn't part of the product. They are part of communication between developers. You could as well require people on mailing list to never top-post and always spell correctly, to reduce cognitive load. Some people actually do that, but they are pretty annoying. :)
  - goostavos 7y ago
    I'm in that camp that doesn't enforce consistent styling in code or even particularly believe in the value of linting at all! ^_^ I'm pretty much just echoing what others have said, but when I look back at the things that have caused problems / mattered in a codebase, things like formatting are generally ranked an order of magnitude below everything else. If people care, I'm happy to oblige, but it always seems like a missing the forest for the trees kind of thing.
  - int_19h 7y ago
    I used to be in the camp that cared a lot about formatting, but over time realized that it's more my OCD than any practical reason. At this point, the only reason why I like consistent code formatting rules is because they prevent bickering between people who have strong opinions on how things should be. When there's a rule, even if people don't like it, they abide by it. When there are no rules, everybody who thinks that there should be rules starts bikeshedding what they ought to be. But as far as code quality goes, I don't think it matters much.
- cmsefton 7y ago
  If that's the case, why have standards when it comes to writing code, e.g. when to use camel case? Why have styles at all for writing in a language like English that tell you how titles should be formatted? Consistent format and structure reduces cognitive load IMO, because it breeds familiarity. Also, Git itself uses the imperative mood whenever it creates a commit on your behalf. Consistency is good.
- u801e 7y ago
  > The issue is being nitpicky about what exact form is being used like whether to capitalize first letter or not. How many code bases have you worked with that don't bother enforcing some type of standard with spacing/usage of tabs, indentation, variable names, method names, import order etc? People don't typically view those rules/conventions as nitpicky. Why should that change with commit messages?
- plorkyeran 7y ago
  People absolutely do question if it is important to write clear commit messages. I've had quite a few conversations where people have said things along the lines of "why do you even care? no one ever looks at the commit meesages".
taneq 7y ago
Also it's a good litmus test for whether you really know what you changed. If you can't describe what you did in a couple of lines, you either did too much or lacked clarity.
- remilouf 7y ago
  I second that. I find that it helps junior dev find the sweet spot in commit granularity.
afarrell 7y ago
> Think of it like a short email that explains to your (future) colleagues and future self Note that commit messages don’t live with the code. If you find yourself writing why something should be in the new state, consider putting that “explain why” as a comment next to the code, so anyone’s text editor can read it.
- jerieljan 7y ago
  Hmm, I think it depends on the case. Sometimes it's appropriate to leave comments on the file, while sometimes trivial changes don't need to be mentioned and explained only at a commit message. Oh and while it doesn't "live" with the code, I can at least look up a line in question and see which commits have changed it, along with their commit messages.
  - Sir_Substance 7y ago
    >Oh and while it doesn't "live" with the code, I can at least look up a line in question and see which commits have changed it, along with their commit messages. The first job I had, I was working on software that had originally been developed by a software engineer but had then been passed to the stewardship of non-programmers. Originally, it had been checked into CVS (yeah, it was that old), but the non-programmers didn't know what that was or how to use it, so when they started making experimental edits, they just copied the source folder to a new location and labelled it "NEW <project>". By the time I got involved there were over 200 of these folders on the network drive, it was unclear which one if any represented the head revision, and the machine with CVS on it had long ago been lost and existed only as a legend. This wasn't insignificant software by the way. I don't feel like telling you exactly what it was, but it was an intense physics simulation and it has quietly impacted probably around a million lives over the last few decades. The point is, don't assume your commit messages are as permanent as your code, they're not. Non-developers just barely grasp source code being important but they don't understand VCS history /at all/. Put important comments in your code.
    - u801e 7y ago
      > By the time I got involved there were over 200 of these folders on the network drive, it was unclear which one if any represented the head revision, and the machine with CVS on it had long ago been lost and existed only as a legend. Fortunately, DVCSs don't have that problem because the meta-information is stored in a folder within the source. So unless the non-developer deletes that folder in every single project, then the information won't be lost (but it wouldn't get updated either).
Waterluvian 7y ago
Commit messages are a poor place to document code because they don't stay with the code. If the code isn't obvious, comments work wonders and often make the commit message more focused on documenting commit history not actual code.
- samyuyitung 7y ago
  I agree that when writing confusing code, it is best to add a comment to explain it. However, in cases where the line isn't commented being able to `git blame` a section/line and read the commit message it was part of to understand the context for it can be invaluable at time.
  - Waterluvian 7y ago
    That's a good point. I think git blame is underutilized in my world.
- nemoniac 7y ago
  These are two different things. A coment in code describes the state of the code as it is. A commit message describes a change in the code, a delta.
  - Retra 7y ago
    A comment in the code can do both, and it should. You should explain why your code is the way it is, not just what it does. Anybody can see what code does by just reading the code.
    - int_19h 7y ago
      There's still a distinction between describing why the code is the way it is, and why it evolved the way it is over time. The latter is what commits capture.
      - Retra 7y ago

lmilcin 7y ago

Nobody questions it is important to write clear commit messages. The issue is being nitpicky about what exact form is being used like whether to capitalize first letter or not. When I look at the repository I am happy if I can understand the messages at all. It's challenging to get people to group changes in a logical way so that the commit makes sense. I am not going to pick on somebody because he used wrong tense or did not capitalize first word of the message if the changes are grouped logically and the commit mentions the correct ticket and purpose of the commit.

remilouf 7y ago
I feel it reduces cognitive load, like proper formatting of code. Do you enforce consistent code formatting in your codebase (using CI, maybe)? If so, why wouldn’t you do that with commits?
- bjourne 7y ago
  Because the commit messages, just like email messages, isn't part of the product. They are part of communication between developers. You could as well require people on mailing list to never top-post and always spell correctly, to reduce cognitive load. Some people actually do that, but they are pretty annoying. :)
- goostavos 7y ago
  I'm in that camp that doesn't enforce consistent styling in code or even particularly believe in the value of linting at all! ^_^ I'm pretty much just echoing what others have said, but when I look back at the things that have caused problems / mattered in a codebase, things like formatting are generally ranked an order of magnitude below everything else. If people care, I'm happy to oblige, but it always seems like a missing the forest for the trees kind of thing.
- int_19h 7y ago
  I used to be in the camp that cared a lot about formatting, but over time realized that it's more my OCD than any practical reason. At this point, the only reason why I like consistent code formatting rules is because they prevent bickering between people who have strong opinions on how things should be. When there's a rule, even if people don't like it, they abide by it. When there are no rules, everybody who thinks that there should be rules starts bikeshedding what they ought to be. But as far as code quality goes, I don't think it matters much.
cmsefton 7y ago
If that's the case, why have standards when it comes to writing code, e.g. when to use camel case? Why have styles at all for writing in a language like English that tell you how titles should be formatted? Consistent format and structure reduces cognitive load IMO, because it breeds familiarity. Also, Git itself uses the imperative mood whenever it creates a commit on your behalf. Consistency is good.
u801e 7y ago
> The issue is being nitpicky about what exact form is being used like whether to capitalize first letter or not. How many code bases have you worked with that don't bother enforcing some type of standard with spacing/usage of tabs, indentation, variable names, method names, import order etc? People don't typically view those rules/conventions as nitpicky. Why should that change with commit messages?
plorkyeran 7y ago
People absolutely do question if it is important to write clear commit messages. I've had quite a few conversations where people have said things along the lines of "why do you even care? no one ever looks at the commit meesages".

taneq 7y ago

Also it's a good litmus test for whether you really know what you changed. If you can't describe what you did in a couple of lines, you either did too much or lacked clarity.

remilouf 7y ago
I second that. I find that it helps junior dev find the sweet spot in commit granularity.

afarrell 7y ago

> Think of it like a short email that explains to your (future) colleagues and future self Note that commit messages don’t live with the code. If you find yourself writing why something should be in the new state, consider putting that “explain why” as a comment next to the code, so anyone’s text editor can read it.

jerieljan 7y ago
Hmm, I think it depends on the case. Sometimes it's appropriate to leave comments on the file, while sometimes trivial changes don't need to be mentioned and explained only at a commit message. Oh and while it doesn't "live" with the code, I can at least look up a line in question and see which commits have changed it, along with their commit messages.
- Sir_Substance 7y ago
  >Oh and while it doesn't "live" with the code, I can at least look up a line in question and see which commits have changed it, along with their commit messages. The first job I had, I was working on software that had originally been developed by a software engineer but had then been passed to the stewardship of non-programmers. Originally, it had been checked into CVS (yeah, it was that old), but the non-programmers didn't know what that was or how to use it, so when they started making experimental edits, they just copied the source folder to a new location and labelled it "NEW <project>". By the time I got involved there were over 200 of these folders on the network drive, it was unclear which one if any represented the head revision, and the machine with CVS on it had long ago been lost and existed only as a legend. This wasn't insignificant software by the way. I don't feel like telling you exactly what it was, but it was an intense physics simulation and it has quietly impacted probably around a million lives over the last few decades. The point is, don't assume your commit messages are as permanent as your code, they're not. Non-developers just barely grasp source code being important but they don't understand VCS history /at all/. Put important comments in your code.
  - u801e 7y ago
    > By the time I got involved there were over 200 of these folders on the network drive, it was unclear which one if any represented the head revision, and the machine with CVS on it had long ago been lost and existed only as a legend. Fortunately, DVCSs don't have that problem because the meta-information is stored in a folder within the source. So unless the non-developer deletes that folder in every single project, then the information won't be lost (but it wouldn't get updated either).

Waterluvian 7y ago

Commit messages are a poor place to document code because they don't stay with the code. If the code isn't obvious, comments work wonders and often make the commit message more focused on documenting commit history not actual code.

samyuyitung 7y ago
I agree that when writing confusing code, it is best to add a comment to explain it. However, in cases where the line isn't commented being able to `git blame` a section/line and read the commit message it was part of to understand the context for it can be invaluable at time.
- Waterluvian 7y ago
  That's a good point. I think git blame is underutilized in my world.
nemoniac 7y ago
These are two different things. A coment in code describes the state of the code as it is. A commit message describes a change in the code, a delta.
- Retra 7y ago
  A comment in the code can do both, and it should. You should explain why your code is the way it is, not just what it does. Anybody can see what code does by just reading the code.
  - int_19h 7y ago
    There's still a distinction between describing why the code is the way it is, and why it evolved the way it is over time. The latter is what commits capture.
    - Retra 7y ago