Hacker News Reader

There are two sorts of comments - "What" comments and "Why" comments.

"What" comments tell you what the code is doing. In a lot of cases, depending on the language, the need for these can be reduced by writing clear code. This is much easier in, say, Python than Assembly. Even in Python though, sometimes you can be doing something a bit subtle where a 2 line comment can clear things up. These comments aren't irreplaceable because with a bit of reading and work, you have all the information to work out what is happening.

"Why" comments are much more important - telling the reader WHY the code is doing whatever it is that it's doing. The 'trim()' comment referenced in the article is a great example of a Why comment - all the reading around the code wouldn't give you an explanation (although sometimes git blame will).

Many 'what' comments are superfluous, almost no 'why' comments are - they are the collective memory of design decisions that otherwise lives in people's heads.

"all the reading around the code wouldn't give you an explanation (although sometimes git blame will)"

Right, as long as the commit messages talk about the 'why' instead of the 'what'. (e.g. 'Make it look bigger on mobile', instead of 'Add META tag with viewport and scaling')

True. I was mostly thinking of commit messages that say "Fix bug where we don't handle x" implying that this change is to handle X.

I've written some really complicated code that crossed layers (due to a third party embedded & unfixable system working against the spec) where each line had two to three comment lines explaining why the operation below was necessary.

Also, I'm not sure if calling Javadoc interface documentation "redundant" and "obese" is warranted. If it feels useless, it is not verbose enough.

Isn't your example a perfect case of the comments only being necessary because the code is somehow flawed?

From the comment, it sounds like the code is doing a reasonable thing dealing with a complex problem. The complexity of the problem deserves documentation.

Code being somehow flawed and reasonable are not mutually exclusive. It wasn't stated what the actual problem was the code was solving, so I can't say whether it was complex.

The code needed comments because it crossed layers – in general a sign of bad code. So the idea of "if your code needs comments, there's probably something wrong with it" definitely holds.

Sometimes you need not to do bad things to handle a bad situation (e.g. handling a third party embedded & unfixable system working against the spec), but that does not invalidate the fact that comments are an indicator of "somehow flawed code".

I understand what you are saying but personally I'd rather focus on understanding the codebase rather than on grading it. In this context, I often find comments very helpful, especially the "why" comments.

It had to cross layers, because the original implementation was flawed. The $vendor had designed the their protocol stack well, but implemented it against the very spec they wrote – for example, the outer protocol frame length field did not take into account character escape codes which were a property of the inner protocol. Instead of a protocol stack, the escaping has to be handled with a multi-layer state machine.

The vendor knows their protocol is buggy, because in their PC maintenance software they have arbitrarily chosen to start frame sequence numbering one higher than the escape character so that they can avoid triggering the bug in most cases. It still breaks down when the payload contains that prohibited escape code. Service techs are used to the whole thing randomly requiring retries and constantly joke about how repairing the $vendor's stuff has the best billable hours per work done ratio.

I assume given the rest of the context you were not implementing a FIX parser - but you’d find the same escape code layering violations if you were!

This strikes me as a good, but incomplete, taxonomy of comments.

What about comments that describe our assumptions? I guess that's a special-case of 'what' comments. Such comments are often better expressed as assertions in code (i.e. adding more code to improve readability, rather than reworking the code). Assertions have the considerable advantage that they don't go stale as the code is changed.

> although sometimes git blame will

That's a great point. Detailed commit messages are a good way to record the 'why' points. Unlike in-code comments, they don't bloat and dilute the source. Of course, they're also less immediate. (I guess I'm not sold on comment-folding as an answer to this.)

It's also a point in favour of fine-grain commits. If you squash your commits, 'git blame' becomes less able to help you track a line of code back to its original motivations.

Personally I would consider listing assumptions as a 'why' comment.

Knowing the assumptions gives the reader the context for why certain decisions were made, and why they may still be valid decisions or not.

Come to think of it, 'assumptions' is awfully broad. I was thinking of in-code assumptions (We assume x is non-negative), but I think you're thinking of requirements-level assumptions?

I agree that requirements-level assumptions (We assume the Vogon server will allow us to make at most 4 connections at any time) are exactly the sort of thing that should be captured in comments. I'm not sure there's a bright line between assumptions and requirements here, really.

My other point there was that any non-trivial code-level assumption that can reasonably be captured with an assert, should be captured with an assert, in preference over a comment.

If you’re assuming x is non-negative I would want to know why. Is it a function of what x represents in the real world? Is it something that we agreed on but there’s no physical reason x can’t be negative? Did the dev just assume x can’t be negative because it was easy and no one ever talked about it? And if the code looks like it assume x will never be negative but there are no comments explaining why then I’ll assume it just wasn’t thought about/discussed at all and know to be careful around this code.

That way when I go to update this code in the future I know if and why I have to worry about if x could be negative now.

Plenty of "what" comments are valuable. A whole lot of my code is prepended by a few paragraphs describing some algorithm from a paper and a link to the full thing. An outline of "this is what the whole thing end-to-end is doing" is fantastically useful.

Comments can convey hard-won information. Often developers will spend hours digging into an issue and then see a configuration or subtle change as the end result. That inocuous little bit of code is some of the most expensive, and brittle, code in the code base, but there is nothing to suggest it.

They might attempt to capture that knowledge in a git message, but that is destined to be burried in the sands of time.

Absolutely this. The time I find comments really valuable is when they remind me (or someone else) 18 months down the line that the other, obvious way to do this thing is subtly wrong, or when they justify using this particular value (perhaps with a link to some outside reference). Comments are mostly hints and metadata.

For example, in a recent file that deals with the database:

    // note: the ROW() constructor below is required in Postgres 10+ if we're updating a single column

(There was a syntax change from Postgres 9 that was caught by our tests)

    // these are the only meaningful values in Postgres: 
    // see https://www.postgresql.org/docs/11/sql-set-transaction.html

(Justifying why we don't support the whole SQL-standard range of transaction isolation types)

    // on trapping the following two rollback error codes, see:
    // https://www.postgresql.org/message-id/1368066680.60649.YahooMailNeo@web162902.mail.bf1.yahoo.com
    // this is also a good read:
    // https://www.enterprisedb.com/blog/serializable-postgresql-11-and-beyond

(An audit trail for why we catch some error codes but not others that initially look similar)

It takes time to "context up" on code you haven't read in a while (or ever). You have to read it, understand how the parts fit together, understand any gotchas and what purpose it serves for other modules.

All this takes time.

Comments are just a way of speeding up the process of "contexting up". Typically it's done by saving a bit of that mental context as a comment.

Ideally you want to save a piece of context that's easy to express, but took a long time to understand in the first place.

We need to be very clear that the specific thing the author is objecting to is mandatory javadoc - the adding of comments which are just copies of the function name in English and convey no non-obvious information. These are definitely unnecessary for those reading the code. They should only be put in if there are consumers of the API who can only read the javadoc and function signatures, not the code.

(On my Visual Studio theme, comments are green on a dark grey background. What's the significance? Probably none.)

If JavaDoc comments are necessary for documentation but unnecessary for reading / editing the code, then perhaps the editor should deemphasize JavaDoc comments and emphasize normal comments.

I think the same should be true of type annotations. They are important to the compiler and as documentation, but should be deemphasized relative to the actual logic.

I found it surprising that the author didn't mention the possibility of deemphasizing doc comments at the same time that they increase the emphasis of regular comments. Doc comments have value for consumers of libraries, so I'm not always able to remove them, like the author did. However, doc comments have a slightly different syntax, so we can make regular comments prominent, like the author suggests, and we can make doc comments less prominent so they aren't distracting.

I find that adding the mandatory comments everywhere ensures that you won't forget to add that extra line of information when it does make sense. It's a good habit, like looking over your shoulder before switching lanes even when you know there's nobody there.

>The idea of writing code for a machine and adding meta-information for humans to better understand the context isn't a bad idea, it's efficient.

It's a great idea. One of the best. I think many people will agree with that.

But there needs to be an equally effective way to keep the comments up to date. Because in my short experience programming professionally, the insidious part about comments is that as soon as one is shown to be a lie, none of them are reliable anymore. And it's very easy for a comment to become a lie as code evolves.

This is why things like unit tests are more attractive as a form of documentation - if the tests lie, the build fails, forcing you to fix lies.

This is my primary problem with comments. I have worked in very large 20year ol code bases both when I have been on the team for most of that time and when I walked in at the end. In both cases almost half the comments are at least partially incorrect.

I've worked on large, old codebases before, too, and in my experience half the functions are at least partially incorrect (i.e., have bugs), too.

The solution in both cases is the same: when you find problems, fix them. Don't throw out the baby with the bathwater.

Maybe I'm reading the wrong programs, but I haven't seen any unit tests that were an adequate replacement for either comments or out-of-band documentation.

For example, I looked up the SQLite source (which often comes up here as an example of a well-written program), picked the first source file I saw (alter.c), and one of the first comments is this:

    /* The principle used to locate the table name in the CREATE TRIGGER 
    ** statement is that the table name is the first token that is immediatedly
    ** preceded by either TK_ON or TK_DOT and immediatedly followed by one
    ** of TK_WHEN, TK_BEGIN or TK_FOR.

Another great one:

    ** Note that ON cannot be a database, table or column name, so
    ** there is no need to worry about syntax like 
    ** "CREATE TRIGGER ... ON ON.ON BEGIN ..." etc.

What unit test would you write to convey this information? Tests can be helpful but they serve a completely different purpose. You can of course write a test to cover the same ground as these comments (and knowing SQLite, they probably did), but a unit test to poke at corner cases is nowhere near as clear as simply stating what's going on.

I think the article means to suggest that one possible way to nudge programmers to keep comments up-to-date is to have editors that don't make them appear "washed out".

> But there needs to be an equally effective way to keep the comments up to date.

Yeah this is called code review. If someone repeatedly submits code with comments that are out of date then their manager needs to have a one on one with them.

Rust's doctests [1] are pretty useful for weaving some comments into the code while also allowing testing on compilation. If they are out of date, just running the test command will alert you that the code and documentation do not match.

[1] : https://doc.rust-lang.org/rustdoc/documentation-tests.html

As a developer I've gone through:

1. Commenting in the redundant way

2. Avoiding comments where possible

3. Using comments to convey intent in public APIs, and occasionally to explain how something works inline.

#3 came from working totally remote for a year.

> Humans aren't good at reading code. If we were, natural languages would have evolved like that, but they haven't.

Give it some more time. I know it's far fetched, but chances are once human-computer interaction (HCI) is accessible for all humans and they transform into cyborgs (hybrid human and machine), code would be a more efficient means of communication as it is the perfect compromise between binary code (that pure machines understand) and natural languages (that pure humans understand).

As an HCI Researcher, I hope not...

The irony is that the historical branching of PL into VPL and then finally into HCI was all about getting away from code to interact with the computer.

It seems like you haven't been exposed to spaghetti code with a million comments vs well designed modular code with few but useful comments. People don't just dream up that difference, it does often change other programmers' way of thinking about the code and helps convey intent far better than exhaustive comments.

It is true that people often take these ideals too blindly and their beautiful architecture brings little in comparison with simple obvious code. (I'm often a culprit there.)

The problem comes when people go from "good code needs few comments" to "never add comments to your code".

You're mixing up two orthogonal things. Your dichotomy is false, a straw man.

Code overspecifies. As long as there are programmers, the clearest code in the world should still have comments indicating intent. And comments won't save unclear code.

Who's arguing that? OP is talking about how useless comments drown out the few truly important comments.

I think it's motivated reasoning. People don't want to write them and it's difficult to put yourself in the mind of someone else and try to anticipate what issues they could have reading your code. You understand it, it seems obvious to you, therefor it doesn't need comments, which just so happen not to be enjoyable to write.

You can say how you wish comments were done, but in practice a section of code with a lot of comments tends to indicate unresolved complexity. The worst is when you can tell the original author used comments to indicate how they wished the code worked, but it doesn't. Sometimes the comments are from the next maintainer trying to figure out what the hell is going on because there is a bug in there somewhere.

The other problem with comments is multiple maintenance. It's very common for a change to be made to the code but not the comment. Now you've got lies misleading the next poor developer who dives in there.

Documentation comments can be useful, but I cringe when I see lots of comments per block or statement.

> Humans aren't good at reading code.

That's something you can get better at, but it requires discipline and effort. Programmers who have no intention of getting better at it think the comments will save them.

> That's something you can get better at, but it requires discipline and effort. Programmers who have no intention of getting better at it think the comments will save them.

Yeah. And people who make memory errors in C are just bad programmers. At some point people will have to accept that their preconceived notions are just that and not some mythical rule that others have to discover to find enlightenment.

I guess something requiring discipline and effort makes you defensive. You can't really think all programmers are equal. How do you think the good ones got better?

> That's something you can get better at, but it requires discipline and effort.

Find me one programmer who's as fluent in C as in any natural language.

If you think I said anything like that, then you're not as good at natural language as you think. Why would I defend an argument I didn't make?