News for hackers. Stuff that matters.
Re:Maybe comments should explain 'what' (2017) by lukan on Sunday January 04, 2026 @10:45AM (#46489014)
Just curious, you advice against "what" comments?

"assume your reader has total knowledge of programming"

Because if I know my fellow programmers have like me not a total knowledge of programming, what comments before footguns seem useful to me.

Or when there was a hack that is not obvious.

To me it mostly is not a question of taste, but context. Who will read the code?

Re:Maybe comments should explain 'what' (2017) by seba_dos1 on Sunday January 04, 2026 @11:16AM (#46489370)
If you're writing a coding tutorial, you'll want to comment on the "what" indeed. Otherwise it will most likely end up being more distracting than useful, and sometimes even misleading. Exceptions exist, but by virtue of being exceptions there's no catch-all rule for them, so just use your judgment.
Re:Maybe comments should explain 'what' (2017) by epgui on Sunday January 04, 2026 @03:22PM (#46491797)
I almost (?) always advise against “what” comments. I have rarely (if ever?) encountered any cases where “what” comments didn’t have a better (and practical/cheap/easy enough) solution.

In my experience, when I review junior contributors’ code and see “what” comments, it’s usually caused by 1) bad naming, or 2) abstractions that don’t make sense, or 3) someone trying to reinvent maths but incorrectly, or 4) missing tests, or 5) issues with requirement gathering / problem specification, or 6) outright laziness where the contributor doesn’t want to take the time to really think things through, or 7) unclear and overcomplicated code, or… any number of similar things.

At the very least, any time you see a “what” comment, it’s valuable to take notice and try really hard to think about whether the problem the comment tries to solve has a better solution. Take it as a personal challenge.

Re:Maybe comments should explain 'what' (2017) by lukan on Sunday January 04, 2026 @04:06PM (#46492229)
For sure, bad code exists. But if I have to work with bad unclear code, "what" comments are very helpful.

Like something really bad

x=y //triggers method xyz

So I would agree that under controlled conditions, they should not be necessary.

Re:Maybe comments should explain 'what' (2017) by epgui on Monday January 05, 2026 @03:46AM (#46496582)
Two words: referential transparency