4 ms·

I guess so - I suppose contributors should be interested in the 'why', whereas users are more interested in the 'what' and, more importantly, 'how will this aff

by Vinnl 5y ago

I guess so - I suppose contributors should be interested in the 'why', whereas users are more interested in the 'what' and, more importantly, 'how will this affect me?'

OJFord 5y ago
Oh I meant the opposite - a 'what' description (bad) being just an English re-run of the code in the commit ('add missing indentation') vs. 'why' that explains what problem it fixed/feature it added ('fix syntax error on navigating to page blah'). I meant that a good 'why' commit subject that gets propagated to release notes is more likely helpful to an end user - ooh nice yes I have had that problem, cool it's fixed, I don't care exactly what fixed it.
- toomanybeersies 5y ago
  My expectations these days are so low, I'll settle for commit messages a full sentence, of any kind. I don't even get hung up about messages not being written in the imperative mood any more. At least 'add missing indentation' is a few steps better than 'changes', or 'fixed', or dozens of commits with 'WIP' as the commit message.
- pwdisswordfish0 5y ago
  The "commit subject" should be a re-run of the code in the commit—condensed into single, 50-chars or less line. It's the rest of the commit message that should contain the detailed context, which includes the why, but most GitHub users are awful at both the commit summaries and writing the rest of the message. The "collaboration" that takes place on GitHub is bottom-of-the-barrel, and you shouldn't expect anything other than dregs there.
  - OJFord 5y ago
    I don't think anything in the subject or message should be a re-run of the code, in the sense of converting it from programming language to English or whatever natural language. Subject: Reason this commit exists ('why' e.g. 'Fix syntax error navigating to /about') Message: Explanation for code, why it's correct fix, background etc. ('how' I suppose) Code: ... (that which I've called 'what')
    - pwdisswordfish0 5y ago
      > I don't think anything in the subject or message should be a re-run of the code Well, you're just wrong then. These aren't code comments. They're commit summaries. They exist only to answer the question "what?"--tersely. Because they're meant to help you pick out the right one when you're looking at a list of them and don't have the entire diff on the screen. But I don't think we're even in conflict here, because your example ("Fix syntax error[...]") actually shows this. I don't know why you keep calling that "why". It's "what". Any way of thinking of this as answering the question "why" (such as "why am I making this change?") is incidental. You're identifying which commit this is. That's a "what". > Code: ... (that which I've called 'what') What? No, code is never "what", whether you're talking about commits or you actually are working on the code and comments themselves. Code is "how", identifiers/names are "what", and comments and commit messages are "why". See my other reply to Vinnl about how weird it is to mix up "why" and "how" in the same breath.
      - OJFord 5y ago
        Well, I've called it what. The code is what I'm committing; the subject is why I'm committing it; the message is (a continuation of the subject's why and) a description of how I arrived at it, how it applies to the problem, etc. Of course it can be phrased differently ('code is how I'm solving the problem; subject is what problem I'm solving' etc.) - I really don't think it matters much what we call them. Point is that, IMO, the subject especially and to a large extent the rest of the message should focus on the reason for the change, not re-describe the change itself, and framed in a way that's not necessarily end-user oriented but is certainly more detached from the implementation in code. Less ambiguous than what/why/how then: code - the change; subject - the reason for it; message - the explanation of it.
- Vinnl 5y ago
  Haha OK, I think we have different definitions of 'why' and 'what' - I was thinking of 'why' being "why did I solve this problem in this way" and 'what' being "what problem did I solve". So yes, totally agree, your last sentence sums it up nice.
  - pwdisswordfish0 5y ago
    To be fair, it's because OJFord is using really weird nomenclature. Example from their other reply: > Message: Explanation for code, why it's correct fix, background etc. ('how' I suppose) Uh, what? It doesn't make any sense to (correctly) refer to this as "why" at first and then conclude that it must be "how"? Just stick with "why".
    - OJFord 5y ago
      Sure, it's a continuation of 'why', I called the subject that headed it 'why' after all. But a lengthier explanation of 'why' that describes 'how' the contained code applies to the problem I think can be called 'how'. I really don't think what we call them matters much if we agree on what they should contain.
      - pwdisswordfish0 5y ago
        Look at the amount of confusion that idiosyncratic terminology led to among the people here in this discussion alone. Of course it matters. To repeat, first referring to the commit message body as why but then concluding you should call it how (because it can't be "why" since you've already decided that the summary is your "why" (which can't be "what" because you want the code to be your "what"))... is the kind of internal inconsistency that should be all the evidence you need to abandon this campaign to insist on using this terminology. And speaking of inconsistency and insistence: if you truly think it doesn't matter, then there's no reason to insist on defending it. The only reason to do so would be if you didn't actually believe that it doesn't matter, and you just said it didn't because it seemed like a convenient way to argue that the weirder nomenclature is acceptable. But again, if it truly doesn't matter, then you'd have no problem letting go of that, right?

by Vinnl 5y ago

I guess so - I suppose contributors should be interested in the 'why', whereas users are more interested in the 'what' and, more importantly, 'how will this affect me?'

OJFord 5y ago

Oh I meant the opposite - a 'what' description (bad) being just an English re-run of the code in the commit ('add missing indentation') vs. 'why' that explains what problem it fixed/feature it added ('fix syntax error on navigating to page blah'). I meant that a good 'why' commit subject that gets propagated to release notes is more likely helpful to an end user - ooh nice yes I have had that problem, cool it's fixed, I don't care exactly what fixed it.

toomanybeersies 5y ago
My expectations these days are so low, I'll settle for commit messages a full sentence, of any kind. I don't even get hung up about messages not being written in the imperative mood any more. At least 'add missing indentation' is a few steps better than 'changes', or 'fixed', or dozens of commits with 'WIP' as the commit message.
pwdisswordfish0 5y ago
The "commit subject" should be a re-run of the code in the commit—condensed into single, 50-chars or less line. It's the rest of the commit message that should contain the detailed context, which includes the why, but most GitHub users are awful at both the commit summaries and writing the rest of the message. The "collaboration" that takes place on GitHub is bottom-of-the-barrel, and you shouldn't expect anything other than dregs there.
- OJFord 5y ago
  I don't think anything in the subject or message should be a re-run of the code, in the sense of converting it from programming language to English or whatever natural language. Subject: Reason this commit exists ('why' e.g. 'Fix syntax error navigating to /about') Message: Explanation for code, why it's correct fix, background etc. ('how' I suppose) Code: ... (that which I've called 'what')
  - pwdisswordfish0 5y ago
    > I don't think anything in the subject or message should be a re-run of the code Well, you're just wrong then. These aren't code comments. They're commit summaries. They exist only to answer the question "what?"--tersely. Because they're meant to help you pick out the right one when you're looking at a list of them and don't have the entire diff on the screen. But I don't think we're even in conflict here, because your example ("Fix syntax error[...]") actually shows this. I don't know why you keep calling that "why". It's "what". Any way of thinking of this as answering the question "why" (such as "why am I making this change?") is incidental. You're identifying which commit this is. That's a "what". > Code: ... (that which I've called 'what') What? No, code is never "what", whether you're talking about commits or you actually are working on the code and comments themselves. Code is "how", identifiers/names are "what", and comments and commit messages are "why". See my other reply to Vinnl about how weird it is to mix up "why" and "how" in the same breath.
    - OJFord 5y ago
      Well, I've called it what. The code is what I'm committing; the subject is why I'm committing it; the message is (a continuation of the subject's why and) a description of how I arrived at it, how it applies to the problem, etc. Of course it can be phrased differently ('code is how I'm solving the problem; subject is what problem I'm solving' etc.) - I really don't think it matters much what we call them. Point is that, IMO, the subject especially and to a large extent the rest of the message should focus on the reason for the change, not re-describe the change itself, and framed in a way that's not necessarily end-user oriented but is certainly more detached from the implementation in code. Less ambiguous than what/why/how then: code - the change; subject - the reason for it; message - the explanation of it.
Vinnl 5y ago
Haha OK, I think we have different definitions of 'why' and 'what' - I was thinking of 'why' being "why did I solve this problem in this way" and 'what' being "what problem did I solve". So yes, totally agree, your last sentence sums it up nice.
- pwdisswordfish0 5y ago
  To be fair, it's because OJFord is using really weird nomenclature. Example from their other reply: > Message: Explanation for code, why it's correct fix, background etc. ('how' I suppose) Uh, what? It doesn't make any sense to (correctly) refer to this as "why" at first and then conclude that it must be "how"? Just stick with "why".
  - OJFord 5y ago
    Sure, it's a continuation of 'why', I called the subject that headed it 'why' after all. But a lengthier explanation of 'why' that describes 'how' the contained code applies to the problem I think can be called 'how'. I really don't think what we call them matters much if we agree on what they should contain.
    - pwdisswordfish0 5y ago
      Look at the amount of confusion that idiosyncratic terminology led to among the people here in this discussion alone. Of course it matters. To repeat, first referring to the commit message body as why but then concluding you should call it how (because it can't be "why" since you've already decided that the summary is your "why" (which can't be "what" because you want the code to be your "what"))... is the kind of internal inconsistency that should be all the evidence you need to abandon this campaign to insist on using this terminology. And speaking of inconsistency and insistence: if you truly think it doesn't matter, then there's no reason to insist on defending it. The only reason to do so would be if you didn't actually believe that it doesn't matter, and you just said it didn't because it seemed like a convenient way to argue that the weirder nomenclature is acceptable. But again, if it truly doesn't matter, then you'd have no problem letting go of that, right?