The Importance of Readability
When I first started coding I believed it was good enough to get stuff working, and then move on to solving the next problem. …
When I first started coding I believed it was good enough to get stuff working, and then move on to solving the next problem. I’d spend a little time designing, but most of my time implementing and testing. My primary concerns were correctness followed by efficiency. I didn’t see the point in re-factoring code until it was time to add new functionality or modules became incompatible or worse incomprehensible! However, once I started to work in a team that was growing linearly I realized that readability is very important for code maintainability because:
1. Other people read your code either because they are learning the code base and need to extend it or because they are trying to figure out how their functionality can fit with yours. If it isn’t immediately obvious what problem the code is trying to solve then they are going to turn to you for help, and if you are around to explain it to them, great. But even then you might have forgotten when you wrote, which then causes them to add new functionality that most likely duplicates your existing solution. Now there are two pieces of code that solve the same problem, and need to be maintained!
2. Other people mimic your code. Before adding new functionality most people read through existing code to see if it solves a similar problem. Instinctually they will copy the pattern, or skeleton of the solution if it applies. Now you have more unreadable code!
So what constitutes as unreadable code?
1. Function names that are ambiguous or functions that perform multiple actions that aren’t reflected in the function name.
public void createBudget(User user, String name, Double amount) {
if (user.getBudget(name) != null) {
user.getBudget(name).setAmount(amount);
}
else {
Budget budget = new Budget();
budget.setName(name);
budget.setAmount(amount);
user.addBudget(new Budget(name)); }
totalSpending(user.getBudget(name));
}
This function is doing more than just creating a budget. It is checking to see if one exists first for the given name, if not then it creates one. If it does exist it updates the amount. Instead of forcing developers to read through the entire function to figure this out a better name would be: createOrUpdateBudget (assuming that eventually more than the amount will change). The same principle exists for variable names as well. In today’s world of coding using and IDE with the auto-complete function saves typing, so long and descriptive variable names are preferable to ambiguous ones like “String s” or “String temp”.
The call to totalSpending makes no sense in this function. If the point is to total up spending for a budgeted category then it should be done outside of the function meant to create a budget. Limiting functionality reduces the levels of redirection a developer has to read through and understand, and makes it easier for them to understand what is going on. Otherwise they have to remember multiple interactions, and juggle them when adding new code.
2. Lumping together function calls.
Looking at the previous example there are multiple function calls lumped together e.g. “user.getBudget(name).setAmount(amount);”. This is done out of convenience, and while in this case the functions are small, and perform simple actions, it becomes much harder to read if the function names are longer and more descriptive. Its best to go through the additional typing, and break them into two separate lines.
e.g. Budget budget = user.getBudget(name);
budget.setAmount(amount);
3. Using private or inner classes.
If a class cannot be reused then it might make sense to create it as an inner or private class. However, the tradeoff is that it becomes harder to search for the class name in IDEs. If you plan to reuse the class because it a basic structure that can be reused then it should be promoted to being a public class.
4. Overbearing parent classes.
Naming is very important to describing the concept that a class is trying to convey. Highly general names should be reserved for parent classes e.g. “Account”. But as you add to the class hierarchy the subclass names should be very specific e.g. “BankAccount” or “CreditAccount”. This also gives developers an intuition of what each class might have as data members. For example, the Account class might have general variable such as “String name”. Whereas its subclasses will contains members that convey the concept of that class e.g. CreditAccount has a variable “Double interestRate” or BankAccount has a variable “Double atmFee”. It also becomes easier to add data members to each of these classes because the classes are divided, and prevents developers from polluting the parent class with too data members that don’t pertain to multiple classes.
5. Function length
Length does matter! Going back to point #1, you should strive to cut down on function length by removing calls to functions that are extraneous, or re-factoring sections into simple single level functions that can be called and re-used.
