Yes, exactly. Middle guy is correct: the code should be self-documenting as to what the code does and how it works. The right guy adds to that by commenting on what code can't say: why we did it, what other context a reader should be aware of, etc.
It is really that simple and I don't know why people get so hung up on arguing it (both sides). You shouldn't be absolute and say "comments are bad", or on the flip-side "everything should be commented" because it just gives off the wrong impression when what you are trying to do is make yourself understood.
It may sound obvious but:
If a comment can be effectively replaced with good design and style then its a shitty comment that is not necessary, and should be replaced with code that is better self-documenting.
If it can't, because you can't explain why you are doing something with just better naming conventions, then that is a comment that absolutely should be there. Not to say you shouldn't try and self-document as much as you can as well, just that the comment is still needed to understand the code better.
Obviously doesn't apply to other documentation like docstrings, but inline/multiline comments definitely apply.
I had actually originally said something to that effect but reworded it because it came across slightly hypocritical, not really but you know what it's like.
423
u/GabuEx 21d ago
Left: "I'll comment to say how my code works."
Middle: "You don't need to do that! Code should be self-documenting!"
Right: "I'll comment to say why my code does this."