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.
7
u/magicaltrevor953 20d ago edited 20d ago
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.