Comment by timr | Hacker News Reader

Comment by timr | Hacker News Reader

"Every comment here is redundant. The textual decoration attempts to assert its own importance, adding two non-semantic lines to every comment. And indeed the eye is drawn to the useless comments instead of the code. So, after looking at these useless comments all day, what do we do? We use our syntax highlighter to turn them off!"

Is it really such a burden to scan a few comments? Come on.

The real problem here is that most developers are total brats about reading code. They'd rather cut off their hand than read anything, and once you're in that mindset, anything that you can latch onto is the target for excessive, self-affirming hostility about the stupidity of the author: those comments are just useless! The idiot who wrote this code must be terrible! I now feel slightly more justified in re-writing everything!

Given that developers almost never write comments for anything, I'd rather see someone erring on the side of over-commenting. If I see code that has been commented in that way, and I see that the other methods are well-commented, I know that the developer was probably more careful than the person who wrote no comments at all. I'm more likely to trust the code. Moreover, having your editor insert a comment on every new method is really a best practice -- it gets you in the habit of documenting, because you always have that empty comment template, staring at you.

You couldn't possibly be more wrong. Comments that describe the code and not the intent are terrible for obvious and clear reasons: They are not checked by the compiler, and they are not checked at runtime. There are no assertions that flag when the comment has gone out of date. Comments that talk about what the implementation does are virtually guaranteed to be wrong. This is simple fact. The thing comments can do that code is less good at is express abstract intent, and they should be saved for that. However, more powerful and expressive languages can express much of that in code as well, and thus even such comments can often be removed.

Look. What is code, and what are comments? Code is stating some fact that is expressed in a well-defined grammar. It can be both 1) read by machines, and 2) read by humans. Code says something specific, and it has a specification or at least a reference implementation which describes the exact meaning of what the code says. Sure, it can be wrong, which simply means that it says something other than what the author intended, but what it says is well specified.

Comments, on the other hand, have no restrictions at all. They can be written in any language. They can be fragments of sentences or multiple paragraphs. If they do follow some structure, it is not enforced unless by some external tool, in which case the comment is, in fact, code as input to that tool, and the complexity of the program has increased by an order of magnitude as it is now written in multiple languages at once.

Comments are worse than useless and should always be seen as the last resort. Wherever there is a comment, there should be a language deficiency that prevented whatever needed to be said from being said in the language itself. If there is no such thing, and the comment merely states what the code already says in a well-defined manner, the comment is wrong and should be removed.

It's fairly ironic that you've spent so many words re-iterating the argument that "code should be self-documenting".

You're right that comments don't maintain themselves, though. That's the job of a programmer, and if the programmer isn't doing their job, they probably shouldn't be working on a project with other people.

> It's fairly ironic that you've spent so many words re-iterating the argument that "code should be self-documenting".

It would be ironic if it was being argued that natural languages are bad. But that is not what's being argued, and the author of that comments was not trying to convey an algorithm to you.

> That's the job of a programmer, and if the programmer isn't doing their job [...]

This is puritanism. Just because it's work, doesn't mean it's useful.

Documenting your code is Puritanism?

Human communication is the rate-limiting process for all software teams. Individual productivity is almost entirely irrelevant, if your personal productivity means that you slow down ten other people.

As i said in a comment further down: Comments are not documentation.

Documentation explains how to use the exposed API to get the code to do something the user desires. It does however not describe what the code does, or why a specific bit of code is done in a certain way.

Comments do not concern themselves with the API, they also do not describe what the code does, that task is up to the code by way of structuring and proper naming of variables and functions.

What is left to the comments is to explain to the guy coming in afterwards why a certain bit of code is as it is when the code or the documentation cannot adequately explain its purpose explicitly or implicitly.

Um.

You're right that code doesn't compile itself, though. That's the job of the computer operator, who takes the code I write in my notebook and flips the corresponding switches on the computer. If the computer operator isn't doing their job, they probably shouldn't be working on a project with other people.

People are fallible. People make mistakes. People get bored. That's why we write tools to do our work for us. The way we avoid making mistakes is by making the mistakes impossible in the first place. This is why typing exists, because without static type checking, people will mix up their types. Yes, it's the job of the programmer to keep their types straight. The compiler doesn't care about types. So what? The whole point of tools is to make the life of the programmer easier, not by magically transforming them into perfect programmers who never make mistakes, but to have tools that avoid, check, verify and catch those mistakes.

Comments circumvent any such tools. Suddenly, you are back to banging rocks together.

Ah yes...the "humans make mistakes, so therefore we should completely ignore all concessions to the people who maintain the system" argument.

Those pesky humans will be much less problematic if they can't communicate in their imprecise meatspeak.

I don't think you understand what I'm saying.

The people who maintain the system are not helped by incorrect information. The information describing how the code works in comments is invariably incorrect. None of the tools we usually employ (unit tests, regression tests, compilation, etc.) apply to the comments, and describing the HOW of code in comments breaks the DRY rule unless the comments ARE the code.

Now, as I said, sometimes you need to describe intent. Most of the time, that is better done through liberal use of functions, purpose-specific types and function names.

For example: In C, there are multiple types of integers defined that all reduce to roughly the same types: size_t, ptrdiff_t, etc. Does the compiler care if the type is unsigned int or size_t? No. Apart from the portability reason for using these types, the other is to describe intent. A variable of the type size_t should store a size. Now, we could make the variable an unsigned int, and in a comment say that "this variable stores a size". But will this comment stay in sync with the code, when the variable later changes to a ptrdiff_t because it is now used to compare pointers? No. The comment won't get changed, because humans are fallible, and changing the comment would require making the same change in two places, one of which is ignored by the toolchain.

Yeah, I got it. Machines can't verify the documentation that humans write. It's not a subtle point.

Now, if the code were good enough to substitute for human-written documentation, you'd actually be addressing my argument. The people who argue that code is self-documenting tend to produce only badly documented code.

The way that comments stay in sync with code is that the developer keeps the comments up to date. It isn't that hard.

Documentation is something completely different from comments. Documentation is something you write for the interfaces you expose. This, I have absolutely no problem with. Interfaces are meant to be stable, they should be well defined, they should have human-friendly instructions and examples on use.

Comments in code? That's something completely different.

I take it you've never written code that someone else had to call into or maintain. You're basically arguing against documentation or explanation of any sort. Also, I assume you program in straight-up English -- all checked by the compiler -- or else some programming language of the future whose contours match the shape of thought and in which there is never any impedance mismatch between what you are trying to achieve and what you must instruct the computer to do.

And please don't say, "That's right, Haskell" or "Yes, my favorite LISP."

No, they're arguing for documentation of intent rather than documentation of what the program does. What the program does is obvious if you have reasonably decent abstractions; what you intend to do is not so obvious.

    // Increase the counter by one
    counter++;

vs

    // Log that a user has viewed the page
    counter++;

and in fact all that vs

    fn logHasViewed() {
        pageViewCounter++;
    }
    
    logHasViewed();

Exactly. To me, even a comment expressing intent is usually a code smell unless it is in a function header. If the block of code is non-obvious enough that it needs an explanation, it should be its own named function, and the function name should describe its purpose.

Of course these are all SHOULDs and not MUSTs. There are always exceptions. But the general rule is definitely that comments are signals that something is broken.

It must depend on what programming culture you find yourself in, but I've seen more undercommenters than overcommenters, often with the excuse that the code is "obvious" or the comment would be literal.

Sometimes literal comments tell you things that you wouldn't pick up skimming the code: for(var i=0;i<length-1;i++) // skip the last element

Or, a comment could give a reason, like "iterate backwards because..."

Sometimes it takes half an hour to work what what two concise lines of code should say -- there may be something tricky going on, or you may be working around a bug in a driver or library or something -- and you should record what you were thinking.

That is true if you read "comment" as "description". That is the weird connection in a lot of bad comment.

But in real life, what is truly a comment (https://en.wikipedia.org/wiki/Comment)? Is like in sports: A commenter talk about the game and add context to enrich the narrative of that game: "Mr. Jhon score a avg of NNN/MMM in this season"

A comment that is a description of what the code is doing, is redundant (if the language is not obscure). But as a "commentary" of the circumstances around that code, is useful:

"This code is a workaround of the BUG (url). TODO: Remove when it get solved".

In other words, comments should explain why something was done and now how.

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.

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

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.

Reply on news.ycombinator.com