Comments Are Code (2018)

I really don’t get the general attitude about comments that prevails. “Good code should be self explanatory” blah blah blah. As if “explains itself” weren’t a pretty damn wishy washy and relative guideline.

And I’ll push back against absolutist arguments about never writing about the “what” too.

So much moaning and whining about the possibility that the comment might get out of sync with the code. Oooh so scary.

Lazy reviewers are the real problem there.

At this point I’m almost a specialist in doing deep dives and deciphering what spaghetti code is actually doing and why. And I make damn sure to write comments to help out the next poor soul.

Comments are very important, but I wouldn't call them "code" because they're not checked. This is one area I predict will be very important in the future, possibly with the help of LLMs: comment checkers. They'll not only ensure the comment isn't factually incorrect, but that there aren't sneaky edge cases (or not-so-sneaky, not-so-edge "oh I forgot to mention [the most important part]...") missing from the comment.

At the risk of sounding tautological I will say that good comments are good and bad comments are bad. Code of which it is unclear why it is the way it is should be commented. Any sort of rule that comments should be written in certain places, e.g., 'comment every public method' train people to write useless comments. In a way writing a comment is an admission of loss. I have failed to write code that was clear enough, so now I have to add a comment. Most code is quite straight forward. As a rule of thumb if you have some code that is neither highly complex nor very straightforward maybe a comment is needed once every one hundred or two hundred lines.

Most compelling argument is to explain "why" not "what". It's what I strive for in commit messages - in order to reconcile changes with the original intent and enable identification of bugs created through misunderstanding.

But commit history gets messy quick...I have food for thought.

We don't have any comments in the code base that I work on now.

Before, for the last couple decades of my career as a programmer, I thought that it was important to have well commented code. I don't believe that anymore. I'm fine with no comments in the code.

If you would have told me that a few years ago, I would have told you you were crazy. But after trying it, it's fine. It works. At their best, comments in code are wasted effort. That's my opinion now after 4 years of working on a code base with zero comments.

Ok the conclusion of this article is totally uncontroversial, and certainly not as punchy as its click-baity title…

> Yes, it’s generally better for code to be self-documenting. In lieu of being dumb for dumb’s sake, however, perhaps add some code comments to provide context for others…or perhaps your future self.

When naming things you should name it what it is not what its for (call it a hammer not a nail driver) you can then make the determination of what you should/shouldn't do with it.

When writing comments, dont say what it does, say why its done that way. If the why doesnt need explination then it doesnt need comments.

Programming is theory building. Comments should only help you understand the theory not the source code. The source code is meant to help you know what the computer will do without interpretation. If you cant read the source code and know what it will do then you NEED to rewrite it. Otherwise just wtite it in assembly it will at least be faster that way.

Also dont include things that are learnable outside the context of your code. Dont explain what a state machine is in your comments. If you must, link to wikipedia or something.

Comments are not checked by the compiler, but I have done some experiments with ChatGPT to find Python functions with code that is inconsistent with their docstrings. When comments are used in an automated way, they do become more like code.

Is it really that hard to write sensible comments?

Well, after a few decades writing software, I've come to the conclusion that yes, yes it is. But just because it can be hard to write a good comment it doesn't mean you need to agonise over it.

Here are a few "simple" examples:

    // Once we receive the cancellation ack, we should automatically send the updated flow
    if (releasedFlow.Status == ReleasedFlowStatus.IndicativeCancelled)
    {
        await _mediator.Send(new SendFlowCommand ...

It should be pretty clear from the context that that's what is happening and it doesn't explain why. This is because it would take multiple paragraphs to explain. Could I just post a link to the documentation about this business rule? Yes, but the location of the said documentation changes so often it can render the comment useless. Could I change it to say something like "Please refer to the documentation"? Sure, but then why don't I put that comment behind every piece of business logic? No, the simple purpose of this comment is just that - a comment on what the business rule was at the time of writing, especially with respect to the other possibilities. You can spend ages overthinking this but there's no point. Just read, understand and move on.

What about this:

    if (foo)
    {
        DoFoo();
    }
    else if (bar)
    {
        DoBar();
    }
    else
    {
        // Intentionally empty
    }

Dead code with a comment that explains nothing. Is this code better with or without the dead code and comment? I'd argue that the code is better with it. In fact, this is a well-known technique: https://en.wikipedia.org/wiki/Intentionally_blank_page

Yes, you can argue that the coder should explain why it's blank. But this depends on the context, and who the intended audience is. Again, no need to overthink it. Read it, modify it if you really think it's necessary (keeping in mind that the alternative is often no comment or empty else statement), and move on with your life.

> I hold an unpopular stance: code comments are as important as the code itself.

It's unpopular because it is astonishingly wrong. Customer: "It does not work". Me: "The comments are correct, the code is not, let's call it a 50/50".

> code comments are critical to code readability and maintainability

Fine, but we are on another level: once the code is right, maintainability becomes important. As long as the code is wrong, fix it and just pray that your code survives long enough for another soul to get a look at it!

I’m a big believer in inline code. Headerdoc kind of stuff encourages just about the correct density of comments.

I’ve learned to unwind the typical spaghetti that passes for code, these days, but every time I do, it reinforces my own posture of leaving a legacy.

Here’s my take on code documentation: https://littlegreenviper.com/miscellany/leaving-a-legacy/

> What’s the big deal about going through the list backward anyway? Perhaps nothing. But if it’s not important, then why not go through the list in a more intuitive way, i.e. starting at index 0? If it is important to go through backward, perhaps it’s important enough to document why. If we don’t comment the why, the reason, the context, we run the risk of a future author changing the algorithm and unwittingly causing some kind of issue because the algorithm ran “better” when searching the list in reverse.

> But wait! The comments will get out of sync with the code! Well, they shouldn’t. When we perform our code reviews, we need to review the comments as well as the code. Comments should be correct, understandable, and valuable; we need to keep these points in mind during our reviews.

I'm not against such "why" comments, but if I really want to make sure such assumptions about code are preserved I strongly prefer unit tests. They don't get out of date accidentally.

> I hold an unpopular stance: code comments are as important as the code itself. It's unpopular because it is astonishingly wrong. Customer: "It does not work". Me: "The comments are correct, the code is not, let's call it a 50/50".

> code comments are critical to code readability and maintainability

Fine, but we are on another level: once the code is right, maintainability becomes important. As long as the code is wrong, fix it and just pray that your code survives long enough for another soul to get a look at it!

Tangential to the author's point, but in Elixir, documentation can literally be code - typically function usage examples that are checked along with other tests. It's a feature I wish other languages had.

https://hexdocs.pm/elixir/1.16.0/docs-tests-and-with.html#do...

I find to be true writing zig that calls into a c-api. Often c cannot express what it really wants to do, so they document it in the comments. But since zig is more expressive than c, I can translate those comments into actual zig code.

A simple example is `Foo * foo`

That could be an input pointer, out parameter, array or it might be allowed to be null.

In zig we can express each one distinctly and all combinations.

This is LinkedIn - not HN - tier content. Comments obviously aren't code, and the idea that they are "as important" is the type of grandstanding you'd perform for a non-developer audience who have no idea what code actually does.

The "why" vs "what" advice is the universal advice everyone has been giving for the last two decades.

I think everybody disparaging the value of having guidelines around reducing comments should be forced to read the script I wrote very early on in coding that started:

```

# 1.1 CSV reading

# read CSV onto a pandas dataframe

df = pd.read_csv("somefile.CSV")

```

I really wish I was joking. . . .

The comments in my code are written with code, and executing them reveals if they are valid or if the code diverged. They are the project test suite.

I have made a system where meta data is encoded in program comments. Definitely heresy!

This is an area where copilot has shone its brightest: writing (acceptable) javadoc.

I like to think that asserts are a form of active documentation

If comments are code, they should all be removed, because they do nothing, and dead code that does nothing should be removed.