3 ms·

I spend a lot of time reviewing code, I currently review every line of code for 16 other developers. Obvious comments are great for code reviews because it's a

I spend a lot of time reviewing code, I currently review every line of code for 16 other developers. Obvious comments are great for code reviews because it's a validation that what you intended to do is what your code actually does. From the article, the comment about adding a vertical scroll bar allows me to review the code and to check that it does indeed add a vertical scroll bar and not something else. Did the developer intend to require password lengths of at least 8 characters? A simple comment would tell me what the developer wanted to do and then I can verify that it was done correctly.

b93rn 5y ago
Great, but that's not the reason why obvious comments are bad. They are bad because it's not maintainable. For you this means that the next time a developer refactors the code, you need to check if the comment is still accurate with the refactored intentions. I repeat, this is not maintainable! I love how the book Clean Code described it: "A comment is a failure to express yourself in code." There are situation they are useful, but those are definitely not obvious comments.
- NicoJuicy 5y ago
  Clean code of a guide, not a requirement. Eg. I like paragraphed comments, because you know what the next 5 lines will do and you can quickly skip to the part you need. It's not always possible to have a method with only 5 lines. There are use-cases where you want a big method doing a lot of things together, because it's complex. Eg. For a government project i needed to connect to the internal network for executing certain requests and all that logic was in one HttpProxyClass, shared between the api + service/deamon
  - b93rn 5y ago
    If those 5 lines do so much that you can't scan it quickly, why is it not in a function? I don't understand, why so many people here have a hard time of understanding this here on HN. You can't trust that comment, you don't know if its outdated or not. Update: I noticed you updated your comment. So my reaction to your addition is that a class can always be abstracted to higher level. It will probably do to much at this point.
    - NicoJuicy 5y ago
      I added the example of what i kept together, because that complex class was the junction class of 4 interfaces for server/client + receive/send. The logic was much simpler to scan/change if you comprehend everything it does. Instead of only partially by abstraction. The use case that one thing was called for one-use case wasn't applicable. I like clean code and apply it a lot. But it's not applicable for everything. I think you just didn't encounter the more advanced cases yet where it isn't, since they are not that frequent. The spirit of clean code is to make readable code. Not the reality is that you have to adjust to the situation. They're is code were comments make sense. Comments can give context and intent ( look at code of sqlite for example).
watt 5y ago
These comments will rot and become confusing/misleading oh so quickly. It's great that somebody is reviewing every single line of code and probably will catch it when folks modify the code but inevitably forget to update the comment, and it becomes out of sync - becomes misleading. If the reviewing is not vigilant that's where you end up: you don't know what to trust, the comment or the code. And the code wins, so that _what_ and _how_ type of comment becomes a net negative.
- uberswe 5y ago
  I see the point. I guess our team just puts the barrier for "useful comment" a bit lower than most other teams. I work with software as a medical device products which has requirements for documentation. Some of this documentation is autogenerated from doc blocks and it is therefore part of the review to also review comments. I understand that my situation will not reflect the average developer. But it is good to see both points of view.

b93rn 5y ago

Great, but that's not the reason why obvious comments are bad. They are bad because it's not maintainable. For you this means that the next time a developer refactors the code, you need to check if the comment is still accurate with the refactored intentions. I repeat, this is not maintainable! I love how the book Clean Code described it: "A comment is a failure to express yourself in code." There are situation they are useful, but those are definitely not obvious comments.

NicoJuicy 5y ago
Clean code of a guide, not a requirement. Eg. I like paragraphed comments, because you know what the next 5 lines will do and you can quickly skip to the part you need. It's not always possible to have a method with only 5 lines. There are use-cases where you want a big method doing a lot of things together, because it's complex. Eg. For a government project i needed to connect to the internal network for executing certain requests and all that logic was in one HttpProxyClass, shared between the api + service/deamon
- b93rn 5y ago
  If those 5 lines do so much that you can't scan it quickly, why is it not in a function? I don't understand, why so many people here have a hard time of understanding this here on HN. You can't trust that comment, you don't know if its outdated or not. Update: I noticed you updated your comment. So my reaction to your addition is that a class can always be abstracted to higher level. It will probably do to much at this point.
  - NicoJuicy 5y ago
    I added the example of what i kept together, because that complex class was the junction class of 4 interfaces for server/client + receive/send. The logic was much simpler to scan/change if you comprehend everything it does. Instead of only partially by abstraction. The use case that one thing was called for one-use case wasn't applicable. I like clean code and apply it a lot. But it's not applicable for everything. I think you just didn't encounter the more advanced cases yet where it isn't, since they are not that frequent. The spirit of clean code is to make readable code. Not the reality is that you have to adjust to the situation. They're is code were comments make sense. Comments can give context and intent ( look at code of sqlite for example).

watt 5y ago

These comments will rot and become confusing/misleading oh so quickly. It's great that somebody is reviewing every single line of code and probably will catch it when folks modify the code but inevitably forget to update the comment, and it becomes out of sync - becomes misleading. If the reviewing is not vigilant that's where you end up: you don't know what to trust, the comment or the code. And the code wins, so that _what_ and _how_ type of comment becomes a net negative.

uberswe 5y ago
I see the point. I guess our team just puts the barrier for "useful comment" a bit lower than most other teams. I work with software as a medical device products which has requirements for documentation. Some of this documentation is autogenerated from doc blocks and it is therefore part of the review to also review comments. I understand that my situation will not reflect the average developer. But it is good to see both points of view.