| ▲ | lukan 4 days ago | ||||||||||||||||
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. | |||||||||||||||||
| |||||||||||||||||