4 ms·
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
by braveo 10y ago
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.
- sqeaky 10y agoI 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.
- emodendroket 10y agoYeah, 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]."
- braveo 10y agoThat'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.