Hacker News Reader

Comment by dfan | Hacker News Reader

The real problem in that case is that every function declaration turned into 1 line of declaration, 2 lines of comments, 1 line of whitespace, and 2 lines of "comment whitespace". Blowing up the amount of vertical space that code takes up by a factor of six really is a problem.

I think the main meta-issue with comments is that they live in the same space as the code at all. For a while I've thought that they might be better as marginal notes like other commentary often is, which is why I'm excited about ideas like Marginalia (http://gdeer81.github.io/marginalia/), though I haven't tried it myself.

View on HN

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.

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.

"Blowing up the amount of vertical space that code takes up by a factor of six really is a problem."

Is it? Maybe I'm the only person who has never experienced this problem. Especially with editor code folding, method nav, tags, etc., vertical space is almost never an issue for me. (Horizontal space, OTOH, is the bane of my existence...)

Marginalia is interesting, though...thanks for the pointer!

There are a few solutions:

- Use a folding editor.

- Buy a bigger monitor.

- Use a split-pane editor with two+ views of one file (e.g. Vim).

- Write shorter functions.

Reply on news.ycombinator.com