3 ms·

Author here. The psychology portion isn't subjective -- things are easier to scan if the more important part is first. One would have a hard time refuting that.

by hmeh 3y ago

Author here. The psychology portion isn't subjective -- things are easier to scan if the more important part is first. One would have a hard time refuting that. Also, there is some familiarity bias that comes into play when reading a commit message style that is foreign, so the experiment I offer may not be super compelling. We are used to what we are used to, and that takes some time to overcome. I know it took me a while to overcome it both in writing, scanning, and reading them. It was worth it for me and our team.

knorker 3y ago
> The psychology portion isn't subjective What's your evidence or supporting research? > things are easier to scan if the more important part is first You skipped the step where "most important" is defined. > "Specifier can be configured when constructing a store" This is just about the worst type of commit message, in my opinion, only marginally better than an empty commit message. Ok. Specifier can be configured when constructing a store. Is it supposed to? Is it the state before or after the commit? Is this just context, and maybe this commit changes documentation to reflect that reality? You even say that reading a bunch of them is uncomfortable. > It's not about the self. It's about the code. Actually, it's about the change. When something broke, what changed. When a new release comes out, what changed. Some people prefer the past form "Added feature X" instead of "Add feature X". On that I just say "be consistent". Also note that your first batch of examples are inconsistent. "Whitespaces", "We don't use `::` to denote class methods", "Avoid __method__", past/present verb form, etc. The difference isn't just the form, but whether commits actually follow any style at all. > I eventually recognized the benefit of scannability Scannability is hugely important. People who disagree with your style of commit message don't disagree with you on that. > For example, "Widget tests" is preferred over "Widget tests are added". What about the widget tests? > When describing a version increase, be explicit about both the old and the new version. E.g., "Package version is increased from 1.1.1 to 1.2.0" Are version numbers ever decreased? (1.1.2 can be released after 1.2.0, yes, but that's not a decrease even if something was backported)
- hmeh 3y ago
  > What's your evidence or supporting research? We didn't need it. It was based on a-priori knowledge. For example, we don't write email subjects like: "Convey information about new release", or "Ask question about time off". We know from how the human brain processes content (eye tracking studies) that they scan in an F-shaped pattern. This puts emphasis on the content on the left. If the left side has no differentiation, this is, de facto, harder to scan. You don't have to agree with me. As my colleague said, there are other, even more subtle things we are trying to convey and reinforce: https://news.ycombinator.com/item?id=38836919 https://news.ycombinator.com/item?id=38836919 > You skipped the step where "most important" is defined. No, we literally do this every time we write a commit message. This is a usability issue. What is the most important thing to the reader? > Ok. Specifier can be configured when constructing a store. Is it supposed to? Is it the state before or after the commit? Is this just context, and maybe this commit changes documentation to reflect that reality? And yet, when all of your commit messages are in a consistent voice and mood, there is no ambiguity. Also, all of your questions are answerable from a self-evident perspective -- if you can rely on your teammates to care about your ability to understand what they write. Of course it's supposed to, otherwise why would I commit it? Of course it's the state after the commit, why would I talk about what was (How many newspaper articles about a celebrity's death have a headline saying they are sick?)? Of course it's not about documentation, it would say it was if it was. In short, you can make up as many holes as you want to poke through. > You even say that reading a bunch of them is uncomfortable. I said at first. See: familiarity bias > What about the widget tests? This is convention that one could argue requires memorization. I don't actually think it does, however, because of how we as humans interpret subjects/headlines. > Are version numbers ever decreased? They have been, and I hope it's self-evident how that commit message would be constructed on our project. In any case, I'm not here to quibble about commit message formats. I documented ours and gave supporting rationale which is based on UX knowledge (and research, at the very least, see eye tracking studies). If you think that "Fix", "Fix", "Add", "Change", are the most important part of the commit message, then I'm not really going to be able to or even bother trying to convince you otherwise.
  - knorker 3y ago
    >> What's your evidence or supporting research? > We didn't need it. It was based on a-priori knowledge. Well, you may hold these truths to be self-evident, but that's hardly an argument. And since you say "It's likely what your team uses, as it is the commit message style that is typically recommended as a "best practice" you acknowledge that you hold a minority opinion. "What I'm saying is self-evidently true" is unlikely to sway anyone. And I find it dishonest to phrase that as "The psychology portion isn't subjective". From your colleague: > The reason that the "subject-first" approach is used is to get contributors to talk specifically to the impacts made to the software itself, rather than talk about themselves and their labors. I don't recognize that description at all about the majority opinion. Yes, some people write terrible commit messages, but that's not the best practice you seek to upend. > Of course it's the state after the commit, why would I talk about what was You'd be surprised. It's more common in bug reports, but I've seen this in commit messages too. >> Are version numbers ever decreased? > They have been, Oh, really? Do you have an example? > In any case, I'm not here to quibble about commit message formats. Thanks for clarifying that you base this policy on nothing but your subjective opinion, that there is no research to support it, and that everyone else is doing it wrong, because your subjective is clearly objective. Nothing wrong with that. I do have a problem with you misrepresenting this as objectively better, with a handwavy "scan in F shape". Don't say it's based on research when it's just your "common sense". That's unprofessional.

by hmeh 3y ago

knorker 3y ago

> The psychology portion isn't subjective What's your evidence or supporting research? > things are easier to scan if the more important part is first You skipped the step where "most important" is defined. > "Specifier can be configured when constructing a store" This is just about the worst type of commit message, in my opinion, only marginally better than an empty commit message. Ok. Specifier can be configured when constructing a store. Is it supposed to? Is it the state before or after the commit? Is this just context, and maybe this commit changes documentation to reflect that reality? You even say that reading a bunch of them is uncomfortable. > It's not about the self. It's about the code. Actually, it's about the change. When something broke, what changed. When a new release comes out, what changed. Some people prefer the past form "Added feature X" instead of "Add feature X". On that I just say "be consistent". Also note that your first batch of examples are inconsistent. "Whitespaces", "We don't use `::` to denote class methods", "Avoid __method__", past/present verb form, etc. The difference isn't just the form, but whether commits actually follow any style at all. > I eventually recognized the benefit of scannability Scannability is hugely important. People who disagree with your style of commit message don't disagree with you on that. > For example, "Widget tests" is preferred over "Widget tests are added". What about the widget tests? > When describing a version increase, be explicit about both the old and the new version. E.g., "Package version is increased from 1.1.1 to 1.2.0" Are version numbers ever decreased? (1.1.2 can be released after 1.2.0, yes, but that's not a decrease even if something was backported)

hmeh 3y ago
> What's your evidence or supporting research? We didn't need it. It was based on a-priori knowledge. For example, we don't write email subjects like: "Convey information about new release", or "Ask question about time off". We know from how the human brain processes content (eye tracking studies) that they scan in an F-shaped pattern. This puts emphasis on the content on the left. If the left side has no differentiation, this is, de facto, harder to scan. You don't have to agree with me. As my colleague said, there are other, even more subtle things we are trying to convey and reinforce: https://news.ycombinator.com/item?id=38836919 https://news.ycombinator.com/item?id=38836919 > You skipped the step where "most important" is defined. No, we literally do this every time we write a commit message. This is a usability issue. What is the most important thing to the reader? > Ok. Specifier can be configured when constructing a store. Is it supposed to? Is it the state before or after the commit? Is this just context, and maybe this commit changes documentation to reflect that reality? And yet, when all of your commit messages are in a consistent voice and mood, there is no ambiguity. Also, all of your questions are answerable from a self-evident perspective -- if you can rely on your teammates to care about your ability to understand what they write. Of course it's supposed to, otherwise why would I commit it? Of course it's the state after the commit, why would I talk about what was (How many newspaper articles about a celebrity's death have a headline saying they are sick?)? Of course it's not about documentation, it would say it was if it was. In short, you can make up as many holes as you want to poke through. > You even say that reading a bunch of them is uncomfortable. I said at first. See: familiarity bias > What about the widget tests? This is convention that one could argue requires memorization. I don't actually think it does, however, because of how we as humans interpret subjects/headlines. > Are version numbers ever decreased? They have been, and I hope it's self-evident how that commit message would be constructed on our project. In any case, I'm not here to quibble about commit message formats. I documented ours and gave supporting rationale which is based on UX knowledge (and research, at the very least, see eye tracking studies). If you think that "Fix", "Fix", "Add", "Change", are the most important part of the commit message, then I'm not really going to be able to or even bother trying to convince you otherwise.
- knorker 3y ago
  >> What's your evidence or supporting research? > We didn't need it. It was based on a-priori knowledge. Well, you may hold these truths to be self-evident, but that's hardly an argument. And since you say "It's likely what your team uses, as it is the commit message style that is typically recommended as a "best practice" you acknowledge that you hold a minority opinion. "What I'm saying is self-evidently true" is unlikely to sway anyone. And I find it dishonest to phrase that as "The psychology portion isn't subjective". From your colleague: > The reason that the "subject-first" approach is used is to get contributors to talk specifically to the impacts made to the software itself, rather than talk about themselves and their labors. I don't recognize that description at all about the majority opinion. Yes, some people write terrible commit messages, but that's not the best practice you seek to upend. > Of course it's the state after the commit, why would I talk about what was You'd be surprised. It's more common in bug reports, but I've seen this in commit messages too. >> Are version numbers ever decreased? > They have been, Oh, really? Do you have an example? > In any case, I'm not here to quibble about commit message formats. Thanks for clarifying that you base this policy on nothing but your subjective opinion, that there is no research to support it, and that everyone else is doing it wrong, because your subjective is clearly objective. Nothing wrong with that. I do have a problem with you misrepresenting this as objectively better, with a handwavy "scan in F shape". Don't say it's based on research when it's just your "common sense". That's unprofessional.