Comments and readable code

At School of Applied Technology you will often get the advice to not use comments. This might feel strange, and especially as a new developer you might have heard in other places that writing comments is a Good Thing (tm).

This post explains a little bit more what we mean, why we recommend writing fewer comments and finally when you should write comments.

Code and readability

Programming code (source code) is a human-friendly (well…) way to give a machine (a computer in our case) instructions. Each programming language have different approaches and often many levels of translations until it becomes executable code for the computer that actually can run.

This means that the code we write is not really the code that the computer executes. Hence the goal of the code we write should be to be clear to other programmers, not the computer. Make sure that the next developer understands your intentions - hey the next developer is probably you later on…

Only optimize and make the code easier for the computer to understand, when you have the need. Turning your JavaScript (or Java, C# or Python or what-have-you) into machine code is the task of the compiler or interpreter. Don’t second guess that unless you have a VERY good reason. Also - if you find such a reason, please call me because I have yet to find one.

Ok - got that clear. Optimize for readability for humans first. At a very distant second, optimize for computer execution speed.

Comments

Just about all programming languages have a feature that helps with readability; comments in code. Comments are lines in the source code that the compiler or interpreter disregards when turning your source code into machine code.

Here’s one example in JavaScript

// Returns true if the age of the person is above 35
// false otherwise
function calculate(a) {
  // check if a is above 35
  return a >= 35;
}

There’s nothing in the comments (lines starting with //) that JavaScript cares about. It’s information for humans that reads the code, to better understand the code. It’s a help to make sense of the code.

Why not comments, then

My suggestion is that you try to avoid comments. And there’s a few reasons for it, but the first one is that it rots over time, and there’s no way to know that it has gone bad.

Check this out, I’ve just made a small change in the code and left everything as it was:

// Returns true if the age of the person is above 35
// false otherwise
function calculate(a) {
  // check if a is above 35
  return a <= 35;
}

The code works perfectly, but it does the opposite now. And the comments are still the same as before. No way of knowing which is the correct one. The code, or the comment?

Now fast forward until a new developer reads this code (or you in 1 month, if you are like me). They will be hecka-confused. And there are no help to be had.

Marcus tells old stories - you can skip this

I worked at one of the biggest Telecom operators in Sweden around the time of the Y2K-problem - look it up kids. Outside one of the offices that was going through all the code written in the company they posted the worst code they found. I swear to God that this was on top of the list, but in COBOL:

// THIS CODE WORKS
// I DON'T KNOW WHY
// DON'T TOUCH IT

And then a compact block of COBOL that I wouldn’t even try to understand. Scary, huh?

Don’t be that programmer.

Better code is better

Ok - but if I don’t write comments wouldn’t that make my code harder to understand? Well… if that is the case, how about making the code easier to understand. Let’s try it.

Here’s the original code again, but without comments:

function calculate(a) {
  return a >= 35;
}

Now, what is this code doing? It’s checking if someone is above 34 years old, by checking the a variable. If we just use that knowledge and give our function and parameters better names:

function isAbove34(age) {
  return age >= 35;
}

Much better. It’s now easy to understand what this function does. But the 34 in the function name is bothering me. What if that rule changes? Is it really to check if someone is above 34 that we are after? No - there’s a (business) concept for that rule. If you are over 34 you are old. Let’s incoorporate that.

function isOld(age) {
  return age >= 35;
}

If we now had types we could make this code even more readable by showing that the function actually expects and does. I’m switching to TypeScript:

function isOld(age : number) : boolean {
  return age >= 35;
}

This is great. Now, without a single comment I can see:

that this function calculate is someone is Old
by using a number parameter called age
and it returns a boolean (true or false) depending on that parameter.

It is easy to understand, without any comments. And the best part is that if I change this code it will actually change how the code behaves. The comments rot, but my code is executed and hence will tell me when something is off.

What do I mean? If someone now wrote a test (YOU! YOU wrote a test, right?) like this:

it('checks if age is considered "old"', () => {
  // act
  const is4ld = isOld(4);
  const is34Old = isOld(34);
  const is104Old = isOld(104);

  // assert
  assert.strictEqual(is4Old, false);
  assert.strictEqual(is34Old, true);
  assert.strictEqual(is104Old, true);
});

And then the implementation changed to age <= 35. First the test would fail. Secondly it would be pretty weird that isOld is true for 4 years, and false for 104. You will get a nudge to change the code.

When to use comments

No rule without exception, right?

There are times when you want to use comments. I can only think of one right now:

If you are writing public API (web or not) that people will use that cannot see the code. Compiled code, or web APIs for example, hides the implementation to the caller. Here comments can be helpful to help the user understand what the code does.

For this we can use [JSDoc]https://jsdoc.app/) for JavaScript or similar constructs for other languages

Beware of documenting obvious things though. For the code above there’s no reason writing that the code expects a number or that it returns a boolean, since that is declared by TypeScript. A good comment would be something like:

/**
 * Determines if someone is old, based on passed in age
 */
function isOld(age : number) : boolean {
  return age >= 35;
}

A bad comment would be:

/**
 * Returns true if age (a number) is above or equal to 35
 * Returns false is age is below 35
 * @param  {number} age
 * @return {boolean}
 */
function isOld(age : number) : boolean {
  return age >= 35;
}

This now have the business rule duplicated and a lot of duplication from the code, in the comments.

Summary

When you find the need to write a comment, see if you can instead make your code easier to understand, so that you don’t need to write a comment. It is much better as source code doesn’t rot as fast as comments.