News for hackers. Stuff that matters.
Re:Fred P. Brooks has passed away by saiya-jin on Friday November 18, 2022 @04:11AM (#33652209)
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.

Re:Fred P. Brooks has passed away by eru on Friday November 18, 2022 @04:39AM (#33652438)
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.
Re:Fred P. Brooks has passed away by rob74 on Friday November 18, 2022 @05:00AM (#33652604)
> 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.

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

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

Re:Fred P. Brooks has passed away by acka on Friday November 18, 2022 @07:49AM (#33653835)
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.
Re:Fred P. Brooks has passed away by saiya-jin on Friday November 18, 2022 @07:26AM (#33653623)
> 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.