5 ms·

> Lesson #4: When you choose specific non-default settings, leave a comment or link to documentation/issues as to why, future people will thank you. Put it in

> Lesson #4: When you choose specific non-default settings, leave a comment or link to documentation/issues as to why, future people will thank you. Put it in the commit message. There is no better place to put it. That is the exact point in time at which you have the most information about that exact change. Commit messages are cheap, be liberal with your words and links. It drives me nuts to read commit messages of the form "fix", "fixed 2", "add test", "new var" and on and on. You took an hour to make the change, take a damn minute to save some future colleague a day of frustration.

RussianCow 7y ago
I agree with you about the importance of commit messages, but the problem with using them in place of comments is that commit messages become much harder to find as the history becomes longer, as opposed to comments which will always be immediately visible for as long as they are relevant.
- jacques_chester 7y ago
  This is what git blame is for. Comments are notorious for drifting out of sync with reality.
  - umvi 7y ago
    Git blame only shows you the last person that touched the line, not the person who introduced a breaking change to that line (but it wasn't caught for weeks/months). Comments are just as cheap as commit messages. Why not both?
    - jacques_chester 7y ago
      It shows you the commit that introduced the current version of the line. That's what you want if you want to understand the current version of the line. I feel like I'm missing something here. I hate this feeling of impending dumb.
      - williamdclt 7y ago
        A line can have been touched multiple times since the breaking change (simplest example: indentation/formatting)
        jacques_chester 7y ago
        Got it. It's still possible to keep stepping back through the history of that line to understand its exact history. I also typically find most files have only a handful of commits of interest in their history, so scoping a git log to the file often gets me within spitting distance of the right commit, if someone took the time to write a good one. Edit: which goes back to my original point, that the commit is the best time and place to snapshot the meaning of that time and that place.
        umvi 7y ago
        I agree, but you must also concede that not all developers are as proficient at git as you and might not be aware of such debugging/detective techniques. These same developers tend to favor print statements for debugging instead of an actual debugger. Also, not every developer has the privilege of using a DCVS like git. For them, a comment in the code could save a lot of time and hassle.
        jacques_chester 7y ago
        Fair points. Though I hope people at gitlab use git.
    - RodgerTheGreat 7y ago
      Git blame can also show you the last revision which touched a file since some revision. Git log on a file can show you all the revisions in which it was touched. Using these together lets you slice the history in many useful ways, and there are countless gui-based tools (git gui, for example) which also allow you to explore revisions.
      - RussianCow 7y ago
        None of that is as effortless as looking up at the comment on the previous line.
        jacques_chester 7y ago
        But which is more effortful to keep accurate. Whereas the commit is immutably and ideally exactly about what it's about. There is no better time to capture the information in a way that perfectly connects it to what it's describing.
        elygre 7y ago
        While commit messages are always there, they get lost. You fix a bug in your code, with a commit message. Later, you realize that this function is super reusable, so you move the function to another class in another file. Now, for all intents and purposes, the original commit message will never be seen again.
        jacques_chester 7y ago
        It's harder to find originals under such circumstances, sure. But I don't see this as a reason for never writing good messages, because a journal of intent is strictly better than a journal of physical amendments. That something needs to be entirely perfect before being judged better than the status quo is the Nirvana fallacy.
        RussianCow 7y ago
    - hinkley 7y ago
      It's more accurate to say that git blame has that information but doesn't make it especially easy to get to.
hinkley 7y ago
So this is something I want to fix about commit messages. If you screw up and forget to add the documentation to the commit message, there is nothing you or I can do about it. And if the commit log is not uniformly useful in this way, then people start to discount the value of the commit messages. And then I have to explain to people who keep cutting and pasting code around improperly are ruining our commit history. I often get a shrug. The first part we could do something about, and I hope we do in the next version control system (there's always a next one). All sorts of metadata should be capable of being attached to a code commit. Some of it stuff we have been relegating to third party tools, which means you can't reason about it as a whole. Did this commit get a green build? Did it have a code review? What PR was it in? Did we run any static analysis? Did we learn after the fact that this code doesn't solve the problem or is a bad solution? If all of this is at my fingertips, I've got a better chance of getting a bunch of people (myself included) to have a broader understanding of the code, or at least an easier time getting familiar with it when I need to.
- jacques_chester 7y ago
  Well there's two things there. One is commit discipline. People care more or they care less, no tool can truly change that. The other is how we collect information. I'm not convinced that version control systems are the right place for that, but I know others have explored it (eg. Fossil SCM). Github provides what is a de facto data store for a lot of such annotations through their APIs, I imagine Gitlab does similar.
  - hinkley 7y ago
    Commit discipline is a wider issue, but building and relying on tools that require humans to never make an error does not scale. People always screw up their commit messages. And once they do it they stop trying because if you can't be perfect you're just torturing yourself to try. If there's a way to fix them after the fact you can begin demanding that people have more commit discipline and make them go back and fix it if they don't get it right the first time. I take it as a matter of Broken Window syndrome. You can try to keep them from getting broken but at some point you have to have a way to fix the ones that break.
sethammons 7y ago
Hi Jacques, your Pivitol is showing :p Commit messages are good, but the dogmatic anti-comment philosophy that Pivitol follows is overdone. Lots (I mean LOTS) of comments are redundant or can be fixed with better naming or organization. But comments shine when dealing with the "why" behind something. I would rather see a comment that says why a value is set to what it is than have to be a git historian.
- jacques_chester 7y ago
  Hi Seth :) Yes, when there's no better alternative, or when it's idiomatic (Go linters) or situationally appropriate (Spring libraries are immaculately commented). But I emphasise "no better alternative" because I have seen comment rot and it sucks badly. The English language is pretty vast and can be usefully ransacked for names. Keyboards are cheap and autocompletion plentiful, so go hog wild with variable names. There are idioms, patterns, well-understood conventions and so on that allow you to avoid noise. When you need a why, then absolutely give the why. But usually the need for an explanation is that the code isn't clear on its face and you should exhaust that possibility first. This concludes today's reading from the Book of Annoyingly Doctrinaire Ex-Labs Pivots. Go in peace.

RussianCow 7y ago

I agree with you about the importance of commit messages, but the problem with using them in place of comments is that commit messages become much harder to find as the history becomes longer, as opposed to comments which will always be immediately visible for as long as they are relevant.

jacques_chester 7y ago
This is what git blame is for. Comments are notorious for drifting out of sync with reality.
- umvi 7y ago
  Git blame only shows you the last person that touched the line, not the person who introduced a breaking change to that line (but it wasn't caught for weeks/months). Comments are just as cheap as commit messages. Why not both?
  - jacques_chester 7y ago
    It shows you the commit that introduced the current version of the line. That's what you want if you want to understand the current version of the line. I feel like I'm missing something here. I hate this feeling of impending dumb.
    - williamdclt 7y ago
      A line can have been touched multiple times since the breaking change (simplest example: indentation/formatting)
      - jacques_chester 7y ago
        Got it. It's still possible to keep stepping back through the history of that line to understand its exact history. I also typically find most files have only a handful of commits of interest in their history, so scoping a git log to the file often gets me within spitting distance of the right commit, if someone took the time to write a good one. Edit: which goes back to my original point, that the commit is the best time and place to snapshot the meaning of that time and that place.
        umvi 7y ago
        I agree, but you must also concede that not all developers are as proficient at git as you and might not be aware of such debugging/detective techniques. These same developers tend to favor print statements for debugging instead of an actual debugger. Also, not every developer has the privilege of using a DCVS like git. For them, a comment in the code could save a lot of time and hassle.
        jacques_chester 7y ago
        Fair points. Though I hope people at gitlab use git.
  - RodgerTheGreat 7y ago
    Git blame can also show you the last revision which touched a file since some revision. Git log on a file can show you all the revisions in which it was touched. Using these together lets you slice the history in many useful ways, and there are countless gui-based tools (git gui, for example) which also allow you to explore revisions.
    - RussianCow 7y ago
      None of that is as effortless as looking up at the comment on the previous line.
      - jacques_chester 7y ago
        But which is more effortful to keep accurate. Whereas the commit is immutably and ideally exactly about what it's about. There is no better time to capture the information in a way that perfectly connects it to what it's describing.
        elygre 7y ago
        While commit messages are always there, they get lost. You fix a bug in your code, with a commit message. Later, you realize that this function is super reusable, so you move the function to another class in another file. Now, for all intents and purposes, the original commit message will never be seen again.
        jacques_chester 7y ago
        It's harder to find originals under such circumstances, sure. But I don't see this as a reason for never writing good messages, because a journal of intent is strictly better than a journal of physical amendments. That something needs to be entirely perfect before being judged better than the status quo is the Nirvana fallacy.
        RussianCow 7y ago
  - hinkley 7y ago
    It's more accurate to say that git blame has that information but doesn't make it especially easy to get to.

hinkley 7y ago

So this is something I want to fix about commit messages. If you screw up and forget to add the documentation to the commit message, there is nothing you or I can do about it. And if the commit log is not uniformly useful in this way, then people start to discount the value of the commit messages. And then I have to explain to people who keep cutting and pasting code around improperly are ruining our commit history. I often get a shrug. The first part we could do something about, and I hope we do in the next version control system (there's always a next one). All sorts of metadata should be capable of being attached to a code commit. Some of it stuff we have been relegating to third party tools, which means you can't reason about it as a whole. Did this commit get a green build? Did it have a code review? What PR was it in? Did we run any static analysis? Did we learn after the fact that this code doesn't solve the problem or is a bad solution? If all of this is at my fingertips, I've got a better chance of getting a bunch of people (myself included) to have a broader understanding of the code, or at least an easier time getting familiar with it when I need to.

jacques_chester 7y ago
Well there's two things there. One is commit discipline. People care more or they care less, no tool can truly change that. The other is how we collect information. I'm not convinced that version control systems are the right place for that, but I know others have explored it (eg. Fossil SCM). Github provides what is a de facto data store for a lot of such annotations through their APIs, I imagine Gitlab does similar.
- hinkley 7y ago
  Commit discipline is a wider issue, but building and relying on tools that require humans to never make an error does not scale. People always screw up their commit messages. And once they do it they stop trying because if you can't be perfect you're just torturing yourself to try. If there's a way to fix them after the fact you can begin demanding that people have more commit discipline and make them go back and fix it if they don't get it right the first time. I take it as a matter of Broken Window syndrome. You can try to keep them from getting broken but at some point you have to have a way to fix the ones that break.

sethammons 7y ago

Hi Jacques, your Pivitol is showing :p Commit messages are good, but the dogmatic anti-comment philosophy that Pivitol follows is overdone. Lots (I mean LOTS) of comments are redundant or can be fixed with better naming or organization. But comments shine when dealing with the "why" behind something. I would rather see a comment that says why a value is set to what it is than have to be a git historian.

jacques_chester 7y ago
Hi Seth :) Yes, when there's no better alternative, or when it's idiomatic (Go linters) or situationally appropriate (Spring libraries are immaculately commented). But I emphasise "no better alternative" because I have seen comment rot and it sucks badly. The English language is pretty vast and can be usefully ransacked for names. Keyboards are cheap and autocompletion plentiful, so go hog wild with variable names. There are idioms, patterns, well-understood conventions and so on that allow you to avoid noise. When you need a why, then absolutely give the why. But usually the need for an explanation is that the code isn't clear on its face and you should exhaust that possibility first. This concludes today's reading from the Book of Annoyingly Doctrinaire Ex-Labs Pivots. Go in peace.