5 ms·

I hate it when I look at some code, wondering why I added a refresh call at that point, I do a git blame to find the commit message, and it says "add refresh ca

by jjcob 1y ago

I hate it when I look at some code, wondering why I added a refresh call at that point, I do a git blame to find the commit message, and it says "add refresh call".

rkomorn 1y ago
But... I keep being told that commit messages are useless because the code is the documentation, so code diffs are self-explanatory...
- dspillett 1y ago
  That only works if the code is good enough to be the documentation. In DayJob prefer to cover all the bases: ∞ Try make the code sensible & readable so it can be the documentation. ∞ Comment well anyway, just in case it isn't as obvious to the reader (which might be me in a few months time) as it is to me when making the change. Excess comments can always be removed later (and, unless some idiot rewrites history, can potentially be referred to after removal if you have a “why t f” moment), comments you never write can't be found later. ∞ Either a directly meaningful commit message, or at very least ticket references to where more details can be found. For personal tinkering, I'm a lot less fastidious.
  - rkomorn 1y ago
    > That only works if the code is good enough to be the documentation. It never actually is at any non-minimal scale (and not even the code authored by the the people who claim code is self documenting). My comment was rhetorical and sarcastic.
- cratermoon 1y ago
  The code is the "how", sometimes it's necessary to explain the "why".
  - rkomorn 1y ago
    Sometimes I wonder if I really do just need to add /s every time I'm being sarcastic.
    - cratermoon 1y ago
      Sometimes I think that people who can't write well enough to convey sarcasm when they mean it should just avoid using it and say what they mean.
      - rkomorn 1y ago
        Now that looks like sarcasm.
      - D-Coder 1y ago
        Unfortunately HN does not support use of the Sarcasm font. /s
  - rkomorn 1y ago
    Sarcasm aside, yes, I 100% agree with you. When the "why" isn't explained, you end up with things like someone refactoring code and spending time (at best) trying to figure out why some tests now fail or (at worst) breaking something in production. I'd argue that even the "how" sometimes is better explained in plain words than in code (even if that opens the door for outdated comments when code is changed).

by jjcob 1y ago

I hate it when I look at some code, wondering why I added a refresh call at that point, I do a git blame to find the commit message, and it says "add refresh call".

rkomorn 1y ago

But... I keep being told that commit messages are useless because the code is the documentation, so code diffs are self-explanatory...

dspillett 1y ago
That only works if the code is good enough to be the documentation. In DayJob prefer to cover all the bases: ∞ Try make the code sensible & readable so it can be the documentation. ∞ Comment well anyway, just in case it isn't as obvious to the reader (which might be me in a few months time) as it is to me when making the change. Excess comments can always be removed later (and, unless some idiot rewrites history, can potentially be referred to after removal if you have a “why t f” moment), comments you never write can't be found later. ∞ Either a directly meaningful commit message, or at very least ticket references to where more details can be found. For personal tinkering, I'm a lot less fastidious.
- rkomorn 1y ago
  > That only works if the code is good enough to be the documentation. It never actually is at any non-minimal scale (and not even the code authored by the the people who claim code is self documenting). My comment was rhetorical and sarcastic.
cratermoon 1y ago
The code is the "how", sometimes it's necessary to explain the "why".
- rkomorn 1y ago
  Sometimes I wonder if I really do just need to add /s every time I'm being sarcastic.
  - cratermoon 1y ago
    Sometimes I think that people who can't write well enough to convey sarcasm when they mean it should just avoid using it and say what they mean.
    - rkomorn 1y ago
      Now that looks like sarcasm.
    - D-Coder 1y ago
      Unfortunately HN does not support use of the Sarcasm font. /s
- rkomorn 1y ago
  Sarcasm aside, yes, I 100% agree with you. When the "why" isn't explained, you end up with things like someone refactoring code and spending time (at best) trying to figure out why some tests now fail or (at worst) breaking something in production. I'd argue that even the "how" sometimes is better explained in plain words than in code (even if that opens the door for outdated comments when code is changed).