4 ms·
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 progra
by epgui 9mo ago
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 9mo agoJust 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 9mo agoIf 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 9mo agoI 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.