News for hackers. Stuff that matters.
Re:Fred P. Brooks has passed away by pjmorris on Friday November 18, 2022 @05:02AM (#33652622)
> 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.

Re:Fred P. Brooks has passed away by Jenk on Friday November 18, 2022 @05:12AM (#33652686)
"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.

Re:Fred P. Brooks has passed away by pjmorris on Friday November 18, 2022 @09:59AM (#33655650)
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

Re:Fred P. Brooks has passed away by kwhitefoot on Friday November 18, 2022 @06:10AM (#33653065)
> 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'.

Re:Fred P. Brooks has passed away by P5fRxh5kUvp2th on Friday November 18, 2022 @09:50AM (#33655512)
In a perfect world, tests and assertions would protect from that, but yes, that's a good use of comments.
Re:Fred P. Brooks has passed away by vjust on Friday November 18, 2022 @11:00AM (#33656646)
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.