Hacker News Reader

Comment by uberswe | Hacker News Reader

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.

View on HN

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.

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

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.

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).

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.

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.

Reply on news.ycombinator.com