Replace Comments with Utility Methods
| | class FuelSystem { |
| | |
| | List<Double> tanks = new ArrayList<>(); |
| | |
| | int getAverageTankFillingPercent() { |
| | double sum = 0; |
| | for (double tankFilling : tanks) { |
| | sum += tankFilling; |
| | } |
| | double averageFuel = sum / tanks.size(); |
| » | // round to integer percent |
| | return Math.toIntExact(Math.round(averageFuel * 100)); |
| | } |
| | } |
Converting comments into constants is one tool that’s available to you. But what if things are more complicated? After all, not everything’s a fixed value.
Here you can see code that calculates an average and manipulates its value before returning it. Can you immediately spot what the last statement is supposed to do? We’d say that the author was absolutely right to clarify the final line with a comment.
From the previous pages, you can probably already guess that we don’t like the comment. But what to do about it?
One alternative would be to create a named variable like this:
| » | int roundedToPercent = Math.toIntExact(Math.round(averageFuel * 100)); |
| | return roundedToPercent; |
This clarifies the code and gets rid of the comment. But it adds another variable to the method, and that one is pretty redundant. After all, it’s returned right away.
Let’s see if we can do better!
The right way to go here is to introduce a utility method. Take a look:
| | class FuelSystem { |
| | |
| | List<Double> tanks = new ArrayList<>(); |
| | |
| | int getAverageTankFillingPercent() { |
| | double sum = 0; |
| | for (double tankFilling : tanks) { |
| | sum += tankFilling; |
| | } |
| | double averageFuel = sum / tanks.size(); |
| » | return roundToIntegerPercent(averageFuel); |
| | } |
| | |
| | static int roundToIntegerPercent(double value) { |
| | return Math.toIntExact(Math.round(value * 100)); |
| | } |
| | } |
You get several advantages from a utility method compared to a comment or an additional variable.
First, the method gets rid of the comment because it says in its name what the code does. That’s also what you would get from a variable. But there are even more advantages.
Second, you don’t need additional lines in the first method. Instead, you now have two methods. Each of them is a little shorter, which makes them easier to understand on their own.
Third, the new method can be reused by other methods. Even if that’s not the case right now, you’ve made the code a little more modular this way.
Fourth, you get a hierarchy of methods: the top-level method getAverageTankFillingPercent() calls the lower-level method roundToIntegerPercent(). This improves the understandability of the higher-level method.
Ideally, each method consists of a series of named statements on a similar level of abstraction. To make this work, we could also extract the code that calculates the average into another utility method. Then we’d have three methods that all work on the same level of indentation.
To sum up, when you replace comments with utility methods, you don’t just get rid of a line of text—you can make your code more modular and balance abstraction levels.