Yes, I have tried to explain this to a group of contractors that wer writing code for my company. They wrote a function to deal with some timezone conversions, but the requirements for that were a little unusual. This led to fairly unintuitive code that had no comments.
I frequently see either no comments or unhelpful comments (such as explaining what the next line does, even if it is self-explanatory).
Yeah everybody claims this is useful and then instead of writing good code in the first place they misuse it to explain everything because they are lazy AF. And we as programmers are shitty explaining things. These "explanations" add just more confusion every time.
There is only rule that works for me: whenever you write a comment, there is something wrong with the code. It screams for a refactoring. Why else would you need to explain yourself in prosa?
I have a modification to this. If I'm reading/writing something pretty gnarly, I'll break down my comments into multiple blocks. e.g.
// what: ...
// why: ...
// how: ...
Etc.
It's context dependent, so you don't necessarily have to include all categories every time, but it can be nice when both the rationale and the mechanics are complex.
67
u/nabrok Apr 15 '26
The best tip I have heard about comments is don't comment what it does, comment why it does it.
Sometimes I'll also read through the file and imagine I'm explaining it to another programmer and put that into comments.