My mission to (almost) eliminate code comments

Recently I’ve started to notice that the majority of comments I write are either redundant, or are excuses for other failings in my code.

Since that realisation, I’ve been making a conscious effort to eliminate the majority of comments from the code I write.

I find that comments generally fall into a handful of common categories. Here’s how I’ve been dealing with each:

Comments that should be methods

I often find myself using a comment, when extracting code to a method would be better.

For example:

I find this much easier to read:

Now I don’t need to understand how free shipping is applied, only that it is applied when this condition is satisfied.

Comments that explain conditionals

I write if statements like this a lot:

That first line conflates two concerns; whether a payment is due, and what to do when it is.

Moving the predicate in to a new variable, with an appropriate name, makes the code easier to read and eliminates the need for the comment:

Note: I might even go one step further here and encapsulate the predicate inside the Order object: order.PaymentDue

Comments as a crutch for poor naming

This most commonly occurs when I’m declaring a variable, then using it some time later.

If that variable is poorly named, I’ll instinctively write a comment explaining what code that uses it is doing.

This is simply fixed by using more descriptive names in the first place:

Note: Shorter functions, where there isn’t a large gap between declaring and using a variable would also help, of course

Comments as an excuse not to refactor

I usually add these comments when I’m writing code that isn’t fully-formed in my head yet.

I have some idea what I need the code to do, so I write the first thing that does the job.

This kind of code is often accompanied by a comment that explains what the code does, rather than why it does it.

What I should do is go back and refactor the code to make it self-documenting, making the comment un-necessary.

Comments that explain why

These comments are probably the only ones I’m going to keep writing.

Sometimes, I come to code I’ve written a while ago and have no idea why it is written in such a strange way.

Often, it’s because I’ve profiled it and found it to be significantly faster, or because it catches an edge-case that a more intuitive method of doing the same thing might not:

Comments like this get to stay.

Summary

The majority of comments I write are a born out of lazy coding, and can be eliminated by simply naming things better or adding more abstraction.

I’m find that when I focus on removing the majority of comments from my code, it actually becomes more readable. The exception is comments that explain why, not how.

If you like this kind of content, I talk about this stuff on Twitter

Developer. Lapsed blogger. 10 years of half-finished git repos.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store