DEV Community

Dave Saunders
Dave Saunders

Posted on • Originally published at davejsaunders.com

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:

if (customersFirstOrder) {
    // Apply free shipping
    orderCost = orderCost - shipping;
}
Enter fullscreen mode Exit fullscreen mode

I find this much easier to read:

if (customersFirstOrder) {
    ApplyFreeShipping();
}
Enter fullscreen mode Exit fullscreen mode

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:

// This order has an outstanding payment
if (order.invoiced && !order.paid) {
    SendReminderEmail();
}
Enter fullscreen mode Exit fullscreen mode

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:

var orderPaymentDue = order.invoiced && !order.paid;
if (orderPaymentDue) {
    SendReminderEmail();
}
Enter fullscreen mode Exit fullscreen mode

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.

var outstanding = GetOutstandingOrders();
...
// Process all oustanding orders
Process(outstanding);
Enter fullscreen mode Exit fullscreen mode

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

var allOutstandingOrders = GetOutstandingOrders();
...
Process(allOutstandingOrders);
Enter fullscreen mode Exit fullscreen mode

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:

// When profiled, running two seperate queries and combining the results in 
// memory is 2x faster that doing the join in SQL
var users = sql.GetUsers();
var tasks = sql.GetAllTasks();
... etc ...
Enter fullscreen mode Exit fullscreen mode

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.


P.S. If you're interested in writing better code, I send out a small code quality tip every Monday.

Top comments (0)