Clean code story — No comments

Why you should prefer short methods to comments, even on already short methods

Recently, I tell a teammate that a method is too long, and should be refactorized to be shorter, and more explicit. I tell him that it’ll allow him to replace him comments. He responds me :

“Why should not use comments? Why it’s better to have short methods? Even if it’s only a private method inside the same class?”

So, for my teammate, and all of us, there is a list of WHY a short method is better, even for already small methods.

1- No language gymnastic

Ok, I agree, this is not the best argument, but still it’s one !

When you read code, your brain adapt himself to read short and condensed names. Used to read PascalCase or whatever naming convention you use. So, when you have comments between lines of code, your brain should change his mind to read literal english (or once again whatever language you use), then re-adapt to code reading, and then again, change to literal language… Morever each comment extends the code length, so the time to read it.

Look how it’s easier to read the version without comments:

2- Use early return in short methods, to make it even shorter

Another argument is that more you use short method, the shorter they could be !

This exemple has more than comments as default for readability. But this will show how short methods and early return can improve your readability and avoid comments.

Even if the code contains more methods declaration, It’s still shorter than the previous version. And obviously more readable. Because methods are named, we understand clearier the context/problem the method should resolve. And because we can use early return, each methods is shorter (no ELSE). As they are shorters, they are off course more readable again.

3- Debugging facilities

Using submethods can help to debug. As the stacktrace will tell you in wich method the problem occurs, and as your methods are short, you can find were faster.

As your code is more readable, as each methods use only parameters they needs, you can find what happen easier.

Some of you we’ll tell me “My debugger tell me the line of code, so I don’t need short methods”. Yes generally debugger does. But when you debug from production log, you can’t have this information (as compiled code is different from source code). So a method name is a good point.

4- Up to date comments

Using short methods, and there names as comment (name are intent based) will create a commented code always up to date !

Let me explains. Imagine you have the following code:

This code sample is pretty simple. And we can understand what happens with comment. But now imagine the following code:

We write the exact same rules, but using coding name, using methods (and constants). Of course, if we want understand how the price is calculated, we need to read the method which do it.

Now imagine, the business rule change. We don’t calculate the price from the number of items, but from their weight, and apply a price of 2.5€ by kilo. If the first version, the change is simple:

But there is a but. There is a probability that the comment upper will not be up to date. Especially if the comment is some lines distant. And if the developer think about it, and change it, he code twice. Once to write the comment, and another one for the code itself.

In the refactorized class, we have something like this:

The business rule is still apparent. And as the method CalculateSendFees has changed, the method to get the number of articles has disapear. Instead, we have a method to get the weight. Your code “reading” is still up to date with the business rule !

5- Easier refactorization and encapsulation

The smaller are your methods, the more understandable they are. And the more you understand what you do, the better you can make it well !

If your methods are shorts, you can then apply the encapsulation principle, and make them reutilisable.

Still on the command “SendPrice” calculation example. Imagine now, we have a new business rule, that is “If a client is at least 60 year old, he get 10% reduction on sending fees”.

Still without comments, the code is always easy to read, and business rules are visible. But we can see that Discount method use client property to make a calculation. We can optimize it:

Now, it look evident ! The IsOver60 method work only on a client. This should be a method of the Client class ! Off course, as the 60 years value is own by the command rules, we’ll make it a parameter of the method.

Now, the “IsAgedOver” can be used by many other context working with client object. May be, we can even make the client birthdate private to make better encapsulation.

Sometimes, you’ll not only add methods to existing object, but create NEW OBJECTS ! For example, if price calculation become more and more complex, we’ll add many submethods. When we think it’s too many, it’s a sign that a new notion emerge from your code. You should probably create a new object or contrat to encapsulate this notion. In this example, we can imagine create a ShipPrice class, using a command to compute the price, or offering some “fluent building interfaces”.

6- Apply it to infinity and beyond

As you can see from the example above, we can apply this principle even on already short methods. This mean you can always (or almost) make your method smaller, and get profits from it !

As your methods get shorter, you can make them even shorter on a next refactorizatio niteration.

There is a rule saying “No more than 5 lines by method”

And as you can see, 5 lines is already big ! You can do better ! Make it explicit ! Make it work for you ! As your methods are shorter, you understand them better ! You can refactorize them better !