97 Things Every Java Programmer Should Know

Chapter 96. Write “Readable Code”

Dave Farley

We have all heard that good code is “readable,” but what does that really mean?

The first principle of readability is to keep the code simple. Avoid lengthy methods and functions; instead, break them into smaller pieces. Name the pieces for what they do.

Automate your coding standards so you can test them in your deployment pipeline. For example, you could fail your build if you have a method of more than 20 to 30 lines of code, or parameter lists of more than 5 or 6 parameters.

Another way toward better readability is to take “readable” literally. Don’t interpret it as meaning “Can I read my code five minutes after I wrote it?” Rather, try to write code that a nonprogrammer could understand.

Here is a simple function:

void function(X x, String a, double b, double c) {
    double r = method1(a, b);
    x.function1(a, r);
}

What does it do? Without looking into the implementation of X and method1, you have no way of telling, programmer or not.

But if instead I wrote this:

void displayPercentage(Display display, String message,
                       double value, double percentage) {
  double result = calculatePercentage(value, percentage);
  display.show(message, result);
}

it would be clear what was going on. Even a nonprogrammer could probably guess from the names what is happening here. Some things are still hidden—we don’t know how the display works or how the ...