When it comes to commenting code there are two sides that often come up in discussion. On one side I’ll regularly hear that code itself is readable so there is no need to comment it. And, typically code does speak for itself. Some elements of code I like commented so I don’t have to think about them each time I scan them, like crazy regular expressions.

On the ofter side of the argument is that all code needs to be commented. In many discussions, including many I’ve contributed to, what and why code needs to be commented isn’t clear. And, the truth is the lines of code themselves don’t usually need to be commented. But, there is a lot that does need to be commented. Here I’ll touch on 3 types of code comments that have little to do with the lines of code themselves.

Why Does The Code Do What It Does?

Have you ever started to work on a project that was already well developed but had few or no comments? I worked on a codebase like that in the past year. I kept asking the question, why did they do it that way? In order to figure that out I had to bug (and in some cases annoy) people to figure it out. I didn’t want to change something important because of my newness and ignorance of the codebase I was working on.

Code comments that explain why something was done in a certain way are really helpful. That context you have in your head while writing code isn’t something the next person will have who touches the code. And, you might not remember it when you work on the code a year from now. Adding that context as code comments can be really helpful.

For example, take a case where code works against an API and while writing it you learn a nuance about the API. Will you always remember that nuance? Will the next person know it who hasn’t done the work you did? Adding a code comment explaining what’s happening can be very helpful in the future.

Another example is to document your assumptions and business rules. Sure, there might be a ticket number in the commit message where the code was added. But, how often do people look at code that way? If details about some assumption or reason are in a code comment it makes it much more clear.

References

Code comments should reference relevant documents, other code, specs, etc. If someone comes along later to work on the code it would be great if they could see the reference used and go read it themselves. It’s much easier and faster than trying to search the web for the right version of the right one. Or, if you go backand what it returns plus any nuance to using it. While the name of a method may tell me what it does that doesn’t mean I know what the inputs are and all possible returns.

If I think of code as a black box, which I often do, I want to know about the inputs and outputs. This is where header comments on functions and methods come in. They explain the inputs and outputs for those who don’t know or remember the internals and don’t need to read the code to use it.

This is popular enough that IDEs and some text editors are able to use these comments to help as we code on the fly.

In Practice

I’ve worked on a lot of code in the past couple years including both overly commented and code without comments. In practice having code comments explaining these three things has made my life a lot easier. And, the absence of them has made it made more difficult to work on a codebase meaning it’s taken more time as well.

Well commented code is just easier to work in.