3 ms·

> 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 dow

> 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.
vjust 4y ago
Grokking that 'why' can take non-trivial mental effort by a non-author, even when well coded/documented. Worse, if the code is needlessly complex, or trying to be smart or over-engineered, any amount of commenting wont help. The non-author (maintainer) of the code is now burdened. And if (so commonly happens) - they dismiss the original code as 'non-performant' or 'not a best practice' or something else.. we know how that plays out.

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.

vjust 4y ago

Grokking that 'why' can take non-trivial mental effort by a non-author, even when well coded/documented. Worse, if the code is needlessly complex, or trying to be smart or over-engineered, any amount of commenting wont help. The non-author (maintainer) of the code is now burdened. And if (so commonly happens) - they dismiss the original code as 'non-performant' or 'not a best practice' or something else.. we know how that plays out.