7 ms·

The why should be clear from the domain that you're working within. A line of comment should count as something like 10 lines of code, if you're reading a comme

The why should be clear from the domain that you're working within. A line of comment should count as something like 10 lines of code, if you're reading a comment then you're treading into real complexity. If you're in a code base where that isn't true, then is the comment really necessary? Fairly hot take from me, life is more ambiguous than that :-).

saiya-jin 4y ago
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.
pjmorris 4y ago
> The why should be clear from the domain that you're working within Sometimes the 'why' is purely domain knowledge. Sometimes the 'why' is about narrowing down options available in the domain. Sometimes the 'why' is about a choice made for reasons that aren't specific to the domain. And sometimes the 'why' is about the code that wasn't written, so it can't possibly be in the code that was.
- Jenk 4y ago
  "Sometimes" doing all the lifting there. Comments are supplemental. If you have just added some weird, non-obvious, bit of code because you needed to compromise, or work around some other quirk, go ahead and comment. No one is going to (sanely) object to that.
  - pjmorris 4y ago
    What you describe is how I tend to comment. At the opposite end of the spectrum we have Knuth's 'literate programming', exemplified in Tex, which has as its goal 'making programs more robust, more portable, more easily maintained, and arguably more fun' [0] by merging documentation with code. I'd bet if you counted documentation lines vs. code lines in Tex they'd be near 50/50, and I'd bet that if we asked Knuth whether the comment lines were supplemental he'd say no. [0] https://www-cs-faculty.stanford.edu/~knuth/lp.html https://www-cs-faculty.stanford.edu/~knuth/lp.html
- kwhitefoot 4y ago
  > sometimes the 'why' is about the code that wasn't written, so it can't possibly be in the code that was. I have often had to write extensive comments related to this to prevent well meaning coders who are not expert in the domain from replacing the apparently bad or low performance code with an obvious but wrong 'improvement'.
  - P5fRxh5kUvp2th 4y ago
    In a perfect world, tests and assertions would protect from that, but yes, that's a good use of comments.
simion314 4y ago
The developers , especially new ones do not understand or know all the history of the project. I remember one time in css I had to do something weird like min-widht:0; It was needed to force the css engine to apply some other rule correctly,. but this will puzzle you when you read it. And this kind of puzzling code needs comments, I prefer to just put the ticket ID there and the ticket should contain the details on what the weird bug was with all the details, so if some clever dev wants to remove the weird code he can understand stuff. Sometimes I see in our old project code like if webkit to X else do Y , there is no comment with a bug link so I have no idea if this code is still needed or not (Browsers still differ in more complex stuff, like contenteditable )
auggierose 4y ago
Code is almost never self-documenting. That's why there are so many O'Reilly books out there. A great example is AWK: It's a tool, and it comes with a book from the people who made the software. That's how I like my software.
- pjmorris 4y ago
  To your point, we also have 'The C Programming Language', K&R, and 'The Unix Programming Environment', K&Pike.
  - auggierose 4y ago
    Seems like the common denominator is the K here!
- vjust 4y ago
  Or the Emacs book.
yourapostasy 4y ago
> The why should be clear from the domain that you're working within. I hear this commonly from coders who haven't had the ambiguous pleasure of working with old, production critical codebases from generations of coders who have come and gone, with technical decisions buffeted around by ever-shifting organizational political and budgeting winds. Knowing the why's that leadership cares about is far more important to your career than the technical why's, which are along for the ride. Once you go into production with tens of thousands of users and up, with SLA's driven by how many commas of money going up in smoke per minute...yeah, illusions of "pure" domain knowledge driving understanding of function dictating code form evaporate like a drop of distilled water on the Death Valley desert hardpan in the middle of summer. I used to be like that as well years ago, but some kind greybeards who took me under their wings slapped that out of me. Now my personal hobby code with an "unlimited" budget and I'm the sole producer and consumer? Yep, far closer to this Platonic ideal where comments are terse and sparse, and the code is tightly coupled to the domain.
P5fRxh5kUvp2th 4y ago
I don't like such rules of thumb. A better approach would be that A comment should tell you something that you cannot glean from the code and/or is non-obvious. Yes, I understand non-obvious can have a truck driven through it, but in general it should work. You can read code and understand what it's doing mechanically, but you may not understand why the obvious approach wasn't taken or understand what it's trying to achieve in the larger context. Feel free to comment on those, but if the code is difficult to understand mechanically, the code is generally bad. Not always, everything has exceptions, but generally that's true.

saiya-jin 4y ago

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.

pjmorris 4y ago

> The why should be clear from the domain that you're working within Sometimes the 'why' is purely domain knowledge. Sometimes the 'why' is about narrowing down options available in the domain. Sometimes the 'why' is about a choice made for reasons that aren't specific to the domain. And sometimes the 'why' is about the code that wasn't written, so it can't possibly be in the code that was.

Jenk 4y ago
"Sometimes" doing all the lifting there. Comments are supplemental. If you have just added some weird, non-obvious, bit of code because you needed to compromise, or work around some other quirk, go ahead and comment. No one is going to (sanely) object to that.
- pjmorris 4y ago
  What you describe is how I tend to comment. At the opposite end of the spectrum we have Knuth's 'literate programming', exemplified in Tex, which has as its goal 'making programs more robust, more portable, more easily maintained, and arguably more fun' [0] by merging documentation with code. I'd bet if you counted documentation lines vs. code lines in Tex they'd be near 50/50, and I'd bet that if we asked Knuth whether the comment lines were supplemental he'd say no. [0] https://www-cs-faculty.stanford.edu/~knuth/lp.html https://www-cs-faculty.stanford.edu/~knuth/lp.html
kwhitefoot 4y ago
> sometimes the 'why' is about the code that wasn't written, so it can't possibly be in the code that was. I have often had to write extensive comments related to this to prevent well meaning coders who are not expert in the domain from replacing the apparently bad or low performance code with an obvious but wrong 'improvement'.
- P5fRxh5kUvp2th 4y ago
  In a perfect world, tests and assertions would protect from that, but yes, that's a good use of comments.

simion314 4y ago

The developers , especially new ones do not understand or know all the history of the project. I remember one time in css I had to do something weird like min-widht:0; It was needed to force the css engine to apply some other rule correctly,. but this will puzzle you when you read it. And this kind of puzzling code needs comments, I prefer to just put the ticket ID there and the ticket should contain the details on what the weird bug was with all the details, so if some clever dev wants to remove the weird code he can understand stuff. Sometimes I see in our old project code like if webkit to X else do Y , there is no comment with a bug link so I have no idea if this code is still needed or not (Browsers still differ in more complex stuff, like contenteditable )

auggierose 4y ago

Code is almost never self-documenting. That's why there are so many O'Reilly books out there. A great example is AWK: It's a tool, and it comes with a book from the people who made the software. That's how I like my software.

pjmorris 4y ago
To your point, we also have 'The C Programming Language', K&R, and 'The Unix Programming Environment', K&Pike.
- auggierose 4y ago
  Seems like the common denominator is the K here!
vjust 4y ago
Or the Emacs book.

yourapostasy 4y ago

> The why should be clear from the domain that you're working within. I hear this commonly from coders who haven't had the ambiguous pleasure of working with old, production critical codebases from generations of coders who have come and gone, with technical decisions buffeted around by ever-shifting organizational political and budgeting winds. Knowing the why's that leadership cares about is far more important to your career than the technical why's, which are along for the ride. Once you go into production with tens of thousands of users and up, with SLA's driven by how many commas of money going up in smoke per minute...yeah, illusions of "pure" domain knowledge driving understanding of function dictating code form evaporate like a drop of distilled water on the Death Valley desert hardpan in the middle of summer. I used to be like that as well years ago, but some kind greybeards who took me under their wings slapped that out of me. Now my personal hobby code with an "unlimited" budget and I'm the sole producer and consumer? Yep, far closer to this Platonic ideal where comments are terse and sparse, and the code is tightly coupled to the domain.

P5fRxh5kUvp2th 4y ago

I don't like such rules of thumb. A better approach would be that A comment should tell you something that you cannot glean from the code and/or is non-obvious. Yes, I understand non-obvious can have a truck driven through it, but in general it should work. You can read code and understand what it's doing mechanically, but you may not understand why the obvious approach wasn't taken or understand what it's trying to achieve in the larger context. Feel free to comment on those, but if the code is difficult to understand mechanically, the code is generally bad. Not always, everything has exceptions, but generally that's true.