5 ms·

What I like better is when you are bumbling through code you wrote a while ago trying to figure something out and there it is, a golden comment from past you, t

by matt_s 6y ago

What I like better is when you are bumbling through code you wrote a while ago trying to figure something out and there it is, a golden comment from past you, telling future you why you wrote shit this way. Usually it's some corner case or weirdness in an API you're calling.

kareemm 6y ago
I call writing these comments "being kind to my future self". It's easier to take the time to justify writing these when I think of doing my future self -- or the poor person who has to maintain my code -- a kindness.
uvw 6y ago
It's unfortunate that the younger generation of coders took "comments are code smell" idealogy to heart and are actively against writing comments.
- mcv 6y ago
  Too many comments explain what is going on. That should be obvious from well-written code. But comments why it's done that way can be extremely valuable. And sometimes there is indeed something wrong with the code. In those cases, a comment saying so can save a lot of time analyzing what's wrong with the code.
  - lsaferite 6y ago
    I came to write basically this exact thing FWIW. Always write the why, not the what. It's the clear difference between useful comments and excess noise.
    - lanstin 6y ago
      There are particularly clever one liners that need a bit of unpacking on the what - Python is bad for this but anytime you are patting yourself on the back for the cleverness, a brief note (at least on the test) is probably warrented. I supposed one can code without cleverness but it's less fun :)
      - mcv 6y ago
        Cleverness that hurts readability is not good. Sometimes you can do a lot in a single line without hurting readability (it may even be more readable), but sometimes there's indeed so much to unpack that it's better to show the steps.
  - tenacious_tuna 6y ago
    The counter-argument I've heard is that commit messages are a better tool for those kinds of annotations, especially if there are multiple points across the codebase where a change was made for the same reason. That's exactly what commit messages are designed to do, too. I've seen plenty of comments in code that say "handle case X because of behavior in place Y", that's tied to changes in place Y. I find it more meaningful when I see all those changes together, bundled in a commit diff, with a message on why. In an especially good editor you can even have the title of the commit rendered into the blank space on the end of the line, which I find useful if I'm trying to figure out the past motivation behind a piece of code.
    - mcv 6y ago
      That's a false dichotomy. You can do both. The problem with relying only on commit messages, is that someone examining the code does not see it. You need to dig through the history. People don't do that nearly as often as reading the code. But if you leave a comment with what the issue is, and add a reference to the commit message, you've got the best of both worlds.
    - saagarjha 6y ago
      Sometimes context should really be next to the code it applies to. If I'm adding pull-to-refresh functionality I might have a commit with ten changed files; there's no reason to put "use a dispatch_async to the main queue here so the animation gets put on the next runloop" in the commit message.
- cameronbrown 6y ago
  Comments should explain the "why" and not the "what". The code _should_ explain the what just fine, but it doesn't explain the problem the code is trying to solve at all. If you struggle to explain the why with a docstring or few comments, then that's a sign you didn't decompose the problem enough.
SNACKeR99 6y ago
Came here to say this - I almost never think much of the code I wrote. But when I see a moment in time that I took the care to do something for future me, it's almost the same as looking at an old photo of myself, and thinking, 'Hey, I didn't look half bad back then!"
DonHopkins 6y ago
I always write // XXX comments that mean there's something here I'm supposed to remember but I don't have the time to write it down right now. It's always fun going back over those and trying to reverse engineer what the hell I was thinking at the time.

by matt_s 6y ago

kareemm 6y ago

I call writing these comments "being kind to my future self". It's easier to take the time to justify writing these when I think of doing my future self -- or the poor person who has to maintain my code -- a kindness.

uvw 6y ago

It's unfortunate that the younger generation of coders took "comments are code smell" idealogy to heart and are actively against writing comments.

mcv 6y ago
Too many comments explain what is going on. That should be obvious from well-written code. But comments why it's done that way can be extremely valuable. And sometimes there is indeed something wrong with the code. In those cases, a comment saying so can save a lot of time analyzing what's wrong with the code.
- lsaferite 6y ago
  I came to write basically this exact thing FWIW. Always write the why, not the what. It's the clear difference between useful comments and excess noise.
  - lanstin 6y ago
    There are particularly clever one liners that need a bit of unpacking on the what - Python is bad for this but anytime you are patting yourself on the back for the cleverness, a brief note (at least on the test) is probably warrented. I supposed one can code without cleverness but it's less fun :)
    - mcv 6y ago
      Cleverness that hurts readability is not good. Sometimes you can do a lot in a single line without hurting readability (it may even be more readable), but sometimes there's indeed so much to unpack that it's better to show the steps.
- tenacious_tuna 6y ago
  The counter-argument I've heard is that commit messages are a better tool for those kinds of annotations, especially if there are multiple points across the codebase where a change was made for the same reason. That's exactly what commit messages are designed to do, too. I've seen plenty of comments in code that say "handle case X because of behavior in place Y", that's tied to changes in place Y. I find it more meaningful when I see all those changes together, bundled in a commit diff, with a message on why. In an especially good editor you can even have the title of the commit rendered into the blank space on the end of the line, which I find useful if I'm trying to figure out the past motivation behind a piece of code.
  - mcv 6y ago
    That's a false dichotomy. You can do both. The problem with relying only on commit messages, is that someone examining the code does not see it. You need to dig through the history. People don't do that nearly as often as reading the code. But if you leave a comment with what the issue is, and add a reference to the commit message, you've got the best of both worlds.
  - saagarjha 6y ago
    Sometimes context should really be next to the code it applies to. If I'm adding pull-to-refresh functionality I might have a commit with ten changed files; there's no reason to put "use a dispatch_async to the main queue here so the animation gets put on the next runloop" in the commit message.
cameronbrown 6y ago
Comments should explain the "why" and not the "what". The code _should_ explain the what just fine, but it doesn't explain the problem the code is trying to solve at all. If you struggle to explain the why with a docstring or few comments, then that's a sign you didn't decompose the problem enough.

SNACKeR99 6y ago

Came here to say this - I almost never think much of the code I wrote. But when I see a moment in time that I took the care to do something for future me, it's almost the same as looking at an old photo of myself, and thinking, 'Hey, I didn't look half bad back then!"

DonHopkins 6y ago

I always write // XXX comments that mean there's something here I'm supposed to remember but I don't have the time to write it down right now. It's always fun going back over those and trying to reverse engineer what the hell I was thinking at the time.