This is an odd one for me, 90% of the time I wind up subconsciously ignoring comments that exist in code. It's almost as if I can't see them on the screen. I've been in at least one argument with a coworker where I realized I was ignoring the existence of the comment he was referencing a line above the code we were looking at. On the other side of that, I'm usually adding comments about what's going on all over the place. At least partly to codify what the heck I'm thinking at the time I'm writing it.
To distill that down, document a lot but don't rely on comments you find to be correct.
I read code the way you would a book, constructing this model in my head. Comments to me are a big flashing warning sign saying "this is so important, we added extra comments".
If the comments aren't really that important it will start hurting my ability to read and understand the code quickly.
likewise, if you a comment I wrote, you better sit up and read because it's there for a very good reason.
I'm of the opinion that at the end of the day people need to be able to read code, not use comments as a crutch. There are times when non-obvious things should be documented so developer B doesn't go down the same rabbithole you did, but in general the code should speak for itself.
document gives the context, the code gives the details. If you have both, there should be no real issues with understanding what's going on.
I agree that accurately reading code is important, but no amount of reading just code tell you why something was done.
For a contrived example, why does a specific function/class use an array instead of a dictionary/hash table? A comment explaining that the dictionary was 500x slower in tests could fix that.
I suspect that is exactly the kind of comments you would want someone to "sit up and read" but I didn't want to assume.
Yeah, exactly. If I'm putting comments inside a method (as opposed to the docstring kind of stuff) I'm writing something like "it might seem like it would be better to do [xyz], but that's actually not a good idea because of [abc]."
That's specifically why I said documentation gives the context. Why the API uses a hash table instead of an array is something for the documentation of said API, not code comments.
To distill that down, document a lot but don't rely on comments you find to be correct.