What you describe really is describing the "why", not the "what".

The line between the two is not that blurry: assume your reader has total knowledge of programming, and no knowledge whatsoever of the outside world. Comments about what the code does to bits are the "what"; comments about how the code relates to the outside world are the "why". The rest is a matter of taste and judgment.

▲

lukan 4 days ago | parent [-]

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?

▲

seba_dos1 3 days ago | parent | next [-]

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.

▲

epgui 3 days ago | parent | prev [-]

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.

▲

lukan 3 days ago | parent [-]

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.

	▲	epgui 3 days ago \| parent [-]
		Two words: referential transparency