Hacker News Reader

Comment by Mithaldu | Hacker News Reader

That is not the real problem, it's just an exacerbation of the underlying issue:

Comments must never describe WHAT the code does, but WHY it does so.

The code itself should clearly describe what it does. If you need comments for that, you've written unreadable code and need to write more readable code. Comments that describe the what just absolve the programmer from doing that, while putting more effort on everyone coming after them.

A comment that describes why a certain bit of code does something, describe something that the code itself cannot and thus help everyone.

View on HN

That is a very academic way of looking at it.

In practice, it's often good to have comments that explain what the code is doing, even if the code itself is quite understandable. It can be a lot quicker to read and understand a one-sentence English description than it can be to read 10+ lines of good code. If the code in question generally has accurate comments of this nature, then working with this code becomes far easier.

And then there are always those cases where rather poor code was written in the first place, it lacked comments, and then a maintenance programmer needs to figure out what it does in order to make some changes to it. Real-world constraints prevent the code from being completely rewritten, but adding comments explaining what it does can be invaluable for anyone else who will ever need to deal with the code.

It is not academic at all, but utterly practical. In your example of a 10+ line code block that is preceded by a comment, the correction is to extract that code into a subroutine and name it accordingly and maybe write actual documentation* for the usage of said subroutine.

Your second example is valid, though i have to admit i've not once been in that situation in my years of work, despite often working with legacy code, and suspect it's fairly rare.

* Note here that comments are not documentation, these are two different entities, one being aimed at the maintainer of a library, the other aimed at the user.

Reply on news.ycombinator.com