3 ms·

Unless you are in some trivial startup domain, real domains (TM) have almost fractal-level complexities if you dig deep enough, corner cases, sometimes illogica

Unless you are in some trivial startup domain, real domains (TM) have almost fractal-level complexities if you dig deep enough, corner cases, sometimes illogical rules etc. The "why" is still very much needed since it can have 10 different and even conflicting reasons, and putting it in the code in appropriate amount shows certain type of professional maturity and also emotional intelligence/empathy towards rest of the team. I mean, somebody has to be extremely junior to never experience trying to grok somebody's else old non-trivial code in situation when you need to deliver fix/change on it now. And its fairly trivial to write very complex code even in few lines, which some smart inexperienced juniors (even older, but total skill-wise still juniors) produce as some sort of intellectual game out of boredom.

eru 4y ago
And even more important than the 'why' can be the 'why not'? Ie explanations for implementation choices that haven't been taken for various reasons.
rob74 4y ago
> I mean, somebody has to be extremely junior to never experience trying to grok somebody's else old non-trivial code People are definitely capable of looking at someone else's code and saying "this crap is completely unreadable, we should rewrite it all", while at the same time believing that their own code is perfectly readable and self-documenting.
kasey_junk 4y ago
I’m not a “no comments” maximalist but someone has to be pretty junior to have never experienced a comment that is just completely incorrect. It’s really hard to write a good comment that is only “why”. It’s really hard to keep comments up to date as code is moved and refactored. And an incorrect comment is much more damaging than no comment at all. That’s the driving force behind “self documenting” code. My view is that a comment is sometimes necessary but it is almost always a sign that the code is weak.
- Oddskar 4y ago
  > It’s really hard to keep comments up to date as code is moved and refactored. Hard disagree with this. If your comment is so volatile then that really sounds like there's something architecturally wrong with the code. Most of the time these kind of "comments" can be turned into either a test, or a extensive description that goes into version control. Because commit messages are just that: a comment for a specific moment in time. There are lots of options to inline comments.
  - acka 4y ago
    Which is why I find looking at `git blame` (or one's favorite IDE's/SCM's equivalent) output so very useful in case of undercommented code.
- saiya-jin 4y ago
  > It’s really hard to keep comments up to date as code is moved and refactored I agree with this, but if the explanation for logic has good reason to be there, then keeping comments up-to-date with code changes is very important and it goes back to seniority and empathy I mentioned earlier - if you understand why its there in the first place, and you actually like rest of your team, you are doing too all of you a big favor with updates of comments. Each of us has different threshold for when some text explanation should be provided, which is source of these discussions. But again back to empathy, not everybody is at your coding level, you can save a lot of new joiner's time (and maybe a production bug or two) if they can quickly understand some complex part.

eru 4y ago

And even more important than the 'why' can be the 'why not'? Ie explanations for implementation choices that haven't been taken for various reasons.

rob74 4y ago

> I mean, somebody has to be extremely junior to never experience trying to grok somebody's else old non-trivial code People are definitely capable of looking at someone else's code and saying "this crap is completely unreadable, we should rewrite it all", while at the same time believing that their own code is perfectly readable and self-documenting.

kasey_junk 4y ago

I’m not a “no comments” maximalist but someone has to be pretty junior to have never experienced a comment that is just completely incorrect. It’s really hard to write a good comment that is only “why”. It’s really hard to keep comments up to date as code is moved and refactored. And an incorrect comment is much more damaging than no comment at all. That’s the driving force behind “self documenting” code. My view is that a comment is sometimes necessary but it is almost always a sign that the code is weak.

Oddskar 4y ago
> It’s really hard to keep comments up to date as code is moved and refactored. Hard disagree with this. If your comment is so volatile then that really sounds like there's something architecturally wrong with the code. Most of the time these kind of "comments" can be turned into either a test, or a extensive description that goes into version control. Because commit messages are just that: a comment for a specific moment in time. There are lots of options to inline comments.
- acka 4y ago
  Which is why I find looking at `git blame` (or one's favorite IDE's/SCM's equivalent) output so very useful in case of undercommented code.
saiya-jin 4y ago
> It’s really hard to keep comments up to date as code is moved and refactored I agree with this, but if the explanation for logic has good reason to be there, then keeping comments up-to-date with code changes is very important and it goes back to seniority and empathy I mentioned earlier - if you understand why its there in the first place, and you actually like rest of your team, you are doing too all of you a big favor with updates of comments. Each of us has different threshold for when some text explanation should be provided, which is source of these discussions. But again back to empathy, not everybody is at your coding level, you can save a lot of new joiner's time (and maybe a production bug or two) if they can quickly understand some complex part.