Comments can damage your code maintenance

There's a way to write code that does not require comments

I often see developers promoting code comments as a way to maintainable code. Depending on the comments it’s usually not beneficial to the codebase.

Comments in code can be used as an indication of the codebase quality.

When you see a lot of comments that explain what a class is, what a function does, and what variables are there for then I consider that to be a beginner code base. Even if it’s written by a senior developer.

Comments should not explain code, they should explain how to use the code

In today’s post, I want to share:

• Why we write comments in our code

• Why comments expose your skill level

• Why comments are detrimental to maintainability

• What to do instead of writing comments

The goal of a great developer lies in the balance of building new features and making sure you can continue to build new features, at the same pace. The second part of that definition is what we generally considered as maintainability.

Certain types of comments have a detrimental impact on your long-term code health.

Comments are not bad, but I think they are overused and also used for the wrong reasons. Let me tell you why I think this and give you some insights into what I do instead in my own codebases.

Why we write comments in our code

There are two reasons developers write comments:

1. To explain how their code works

2. To explain how to use their code

The first is for developers in their team that will work on the internals of the codebase. The goal of these comments is to help make their job easier. The hope is that the developer can start improving or making adjustments in the code without having to read through the entire function/class.

The second is commonly associated with writing code for external parties. It provides examples of how to use the code, what the code is used for, and the behavior to expect from the code.

Using comments as mentioned in number 1, to explain how code works, is very detrimental to your long-term maintainability. Let’s look at the reasons why.

Why comments expose your skill level

When I see comments that explain how code works I immediately assume a lack of software engineering skills. There are many to point to but the most important ones are:

• Application of design patterns

• Divide and conquer

• Code organization

• Object naming (Yes, this is a skill 😅)

By applying these 4 skills above and getting good at them you can write code in a way that is self-documenting. The definition of self-documenting code is to use structured design patterns and naming conventions to allow the use and extension of the system without prior knowledge of the specific system.

To achieve a self-documenting codebase we need to individually improve the skills listed above, which can all be practiced daily.

But what exactly is so bad about comments that explain how your code works?

Why comments are detrimental to maintainability

The biggest issue with comments is that it also needs to be maintained.

Comments will become outdated quickly, and you won’t get help from developer tooling to let you know that. In addition to the lack of tooling help, it’s also double the work for any developer. Changes have to be made to the code, and the comments have to be updated.

In my experience, I’ve found more outdated comments around implementation details than comments that are up to date. The experience becomes worse the larger the functions and files that are commented on.

Comments should be to explain to the developer reading it how to use the code. After reading a comment they should understand what they can expect from the function, not how the function works.

If that statement is true, how do we then explain to the developers who need to change that code what it does? Well, this is where a bit of extra work comes in.

What to do instead of writing comments

There are two main ways we ensure developers understand the code they need to change.

1. Writing self-documenting code

2. Using unit tests to document the code

Both of these are compile-time safe but only one of them allows the new developer updating the code to know if they’ve broken anything that’s expected from the function.

If you use unit tests to document how a function works, a developer can read those tests, understand what it should do, and add their new logic. The best way to document very complex functionality is through simple, small unit tests.

The reason this is so effective is that writing those tests will force you to apply all four core software engineering skills required to write and reduce the commentary in your code. It will help you:

• Learn to apply design patterns

• Practice divide and conquer

• Teach you code organization

• Improve your object naming

And the best thing about it is, when you use unit testing to document your complex logic you write self-documenting code in the process. So it’s a win-win.

It’s not easy to do, but it’s absolutely worth it.

Next time you’re writing comments ask yourself, am I writing a comment to explain what my code does, or is it a comment to explain how to use my code?

---