First Principles
- Everything Small, Well Named, Organized, and Ordered
- A More Significant Example
- A Final Thought
This chapter is from the book
This chapter is from the book
This chapter is from the book
)
If you read this chapter and grasp all the principles within, then you’ll be 90% of the way toward cleaning code. The ideas presented here are old and well established. They have stood the test of time and should be part of every programmer’s regimen of discipline.
Keep in mind that these are not strict laws. They are not rules that must be followed. They are, more or less, guidelines. Each should be applied in the context of the problem at hand, and every programmer should feel free to take whatever license is necessary to solve that problem.
But, when all else is equal, and all the variables are averaged out, these are the principles that I believe emanate from well-cleaned code.
If, as you read what follows, you encounter concepts that are foreign or novel, be assured that all will be explained in subsequent chapters. Indeed, when you have finished reading this book, you may wish to complete the circle by rereading this chapter.
Everything Small, Well Named, Organized, and Ordered
If you stop now and read nothing more than that heading, you’ll have much of the essence of what it takes to clean code.
Keep everything small. Choose names for those small elements that communicate to other programmers. Define and maintain a structure and organization that present the software in such a way that others can easily consume it. Keep the elements within that organization well-ordered so that one concept follows another in a rational and sensible way.
Remember that your own understanding of the code will likely bias your attempts at providing good names and structures; so work hard to put yourself in the headspace of those who do not understand the code.
Functions
Functions should be small. Most should be just a handful of lines. This allows them to have nice, descriptive names and promotes the separation of concerns. It ensures that each function does one, and only one, thing.
Let’s start with the name. If you see a snippet of lines that does something that can be reasonably named, then that snippet should be moved into a function named for what that snippet does. The name should be a verb that says what the function does and that allows the calling sequence to read “like well-written prose.”1
As an example, consider this function, adapted from the JCommon library. It finds the date of a specified weekday before a given date. The weekday codes are integers 1 (Sunday) through 7 (Saturday).
public static Date getPreviousDayOfWeek(int weekday, Date from) {
// check arguments…
if (!isValidWeekdayCode(weekday)) {
throw new IllegalArgumentException(
"Invalid day-of-the-week code."
);
}
// find the date…
final int adjust;
final int baseDOW = from.getDayOfWeek();
if (baseDOW > weekday) {
adjust = Math.min(0, weekday - baseDOW);
} else {
adjust = -7 + Math.max(0, weekday - baseDOW);
}
return Date.addDays(adjust, from);
}
There are at least two snippets of code that we could extract into smaller and better-named functions. And those extractions will lead to some simplifications.
public static Date getPreviousDayOfWeek(int weekday, Date from) {
checkWeekdayArgument(weekday);
return addDays(-daysBefore(weekday, from), from);
}
private static void checkWeekdayArgument(int weekday) {
if (!isValidWeekdayCode(weekday))
throw new IllegalArgumentException(
"Invalid day-of-the-week code.");
}
private static int daysBefore(int targetWeekday, Date from) {
int fromWeekday = from.getDayOfWeek();
int diff = fromWeekday - targetWeekday;
return diff + (diff > 0 ? 0 : 7);
}
Notice how the simplified getPreviousDayOfWeek function reads. It’s short, and it’s obvious. If you need to know more, all you have to do is look down to see the extracted functions. However, most often you would not need to know more. You’d simply look at that function, agree with it, and move on. It may not read like the prose of a Crichton novel, but it reads pretty well.
