Comment Overload

Hello!

Welcome to my thoughts. I’ll preface this first entry by talking a little bit about why I wanted to start writing these posts in the first place. I came across this article by Justin Murphy about how knowledge bases are bullshit. He argues that creating a big graph of connections between every idea you have in your head is not conducive to insights, instead, it distracts from real understanding. Real understanding about a topic comes from that deep thought process required for writing about something in a clear way. He describes it as a rather elegant seam that goes through one idea to the next, connecting them in ways that would be impossible if we just randomly record what the connections inside our head are, hence, the title: Personal Knowledge Management is bullshit.

So here I am, writing about whatever I find interesting in order for my mind to grapple it like a Batman gadget, to be able to explain it fluidly, to trace that line between its components which would bring the wisdom that a bunch of dots and lines would never produce.

About comments

Anyways, enough for the corny introduction. The idea for today is comments. Have you paid attention to them lately? Claude seems to love placing them so you (or himself (or itself?)) can understand clearly what’s going on. These comments seem to grow exponentially though, to the degree that I stopped caring about them. My question is, are they good or bad? Should we ask for less of them or more of them?

In an ideal world, comments are never necessary, code expresses itself so clearly and beautifully that you don’t need to explain it with a comment. In reality though, code lives in a world that has context and that context can’t be expressed with code sometimes. So comments are good, but they definitely can be used in the wrong way.

The experiment I designed to explore this idea was based on a small API that managed information about beer and breweries. I wanted to be more original with the topic but of course when you want to think about nuanced topics the most mundane and enticing things come to your mind. And if you know me, I like beer, I hope you, my dear reader, like it as well.

The API had a base setup and a list of subsequent changes that were required (not necessarily in that order), some of them contradictory, to simulate a real-world scenario. Number 2 asked for scores on the beer, number 4 decided that beer brands were not really the focal point, but breweries and that they should hold the scoring. Number 3 asked for paginated answers, number 6 said: “we went too hard on pagination, dial it back to beers only”. You get the gist, I was trying to emulate the constraints of a real-world project as much as I could without sacrificing my whole weekend. I have some WoW to play, ok?

With that list of changes then I would spawn two agents, one tasked with applying the changes without any special instructions, the second one banned from any comment that wasn’t utterly necessary.

The results

Quality is basically the same. Both normal and succinct mode (the one without comments) produced basically the same output, though with some quirks that I want to point out.

First, this is the function produced by the normal mode:

Normal mode:

  const { name } = body;
  const isNonEmptyString = (value: unknown): value is string =>
    typeof value === "string" && value.trim().length > 0;

  if (!isNonEmptyString(name)) {
    res.status(400).json({ error: "name is required" });
    return;
  }

Compared to its succinct counterpart:

Succinct mode:

  const { name } = req.body ?? {};

  if (typeof name !== "string" || !name) {
    res.status(400).json({ error: "name is required" });
    return;
  }

Reveal that when you ask for less comments, not only the comments change, but also the code itself. Leaving aside the fact that this code would never be written, given that you have a library that typechecks the shape of the request for you, my monkey brain calls for the simplicity of the second version over the verbosity of the first one. The reason: instead of creating an abstraction about how isNonEmptyString should look, I will first apply the rudimentary implementation of that validation and later on, maybe with the help of an agent, will abstract the right implementation once I’ve seen this pattern repeat enough times.

So that’s the first takeaway: less comments don’t only mean less comments but also less complicated code.

The second one is more meta and more relevant to big codebases. As I was running the second version of the experiment, I realized that the initial setup was more influential than any of the instructions I gave to the coding agent. Succinct or not, the initial setup for the project structure was followed closely in the downstream changes. At the same time, the function signatures created at the start of the project were also replicated down the line.

I think this is relevant because of the small attention the initial setup gets, both when you start a new project and when you’re planning a new feature. If we give a more clear instruction to the agent about how we want our code to look like, we would end up with less slop to worry about down the line. Spending those extra 30 minutes writing down how our APIs need to look like will save us hours trying to debug that dreadful slop that has 200 uninteresting comments, hiding the real one in plain sight. To that I call: comment overload.

To recap, aim for less comments, as it will reduce the number of ways the same functionality gets expressed, allowing you to catch redundant code at review time and creating better abstractions. And the second one: spend that early planning time to define what the code should do and how it should look. It will pay off greatly.

Thanks for reading and see you next time. Hopefully in less than 3 weeks.