Should I Comment This Code?

26 May 2023

Here are some guidelines for when I might comment code.

Just Right

Code commenting is a Goldilocks effort.

I don't want too many. It makes the code harder to read (the opposite of what comments should accomplish). Huge blocks of text. More confusing than the code. More likely to get out of date. More likely not to be read. Pushing real code offscreen. Splitting code up so it's difficult to see the big picture.

Neither do I want absolutely no comments. Comments aren't always a sign of a failure to write well-factored code. There are some things better given to comments than code. Let's investigate those instances.

The goal of this art will be to identify the circumstances where comments are most useful and then comment just enough and no more.

The Exceptions

Style guides usually work against you. They're usually stated in terms of always doing something. But I think commenting should be an exception, not a rule.

We don't want a comment on every function or whatever. We want to encourage comments when the extra information they provide is a net gain.

Obvious and Repetitive

// this function adds
function add(a, b) {
  return a + b
}

This example function may add. But the comment adds nothing. When to avoid comments:

  • Is it going to be noise?
  • Is this information easily inferred in code?
  • Does it seem repetitive next to the code?

lol

Is there context I can add?

Extra context on top of the written code can be very valuable.

  • Why did we do this?
  • How did we come to this conclusion?
  • Will I forget these reasons later?
  • What are the downstream needs of consumers of this code?
  • What are the environmental prerequisites for this code to function correctly?
  • What are the assumptions we made?
  • What limitations are we functioning under?
  • What future improvements might be made?

English prose in comments is the best tool for providing this information.

Code comments aren't the only place this kind of context can be stored. Git commit messages are also perfect. Merge Request descriptions. Links to ticket tracker descriptions.

Is this unexpected?

Something that is "easily inferred" in the code might not be easy for someone else. For that matter, it might not be easy for your future self.

  • Would someone else likely asky why the code is the way it is?
  • Would my future self?

Usually, the unexpected or not-easily-discovered should be avoided in code. Readability and maintainability usually reign supreme. But sometimes we deviate from this standard on purpose. In those cases, a comment can be helpful:

  • Did we do something odd for performance reasons?
  • Did we do something for another part of the system, something off-screen and not apparently connected to this code?

Beyond Self-documenting Code

Well-factored code can largely be self documenting. We should lean on that ideal. And we shouldn't forsake the ideal of adding comments for extra helpful context or explanation.

We shouldn't let comments take the place of code structures. For instance, we shouldn't add comments to dilineate steps in a large piece of code where we could instead extract functions that encapsulate and name those steps.

But comments can be useful when used judiciously, written tersely and plainly, adding context and explanation for future programmers.