Why Read This Book?
Every developer has a number of requirements in mind that she considers prerequisites for good or clean code. As long as a piece of code doesn’t violate any of these requirements, it qualifies as good or clean from the viewpoint of the developer. Different people have different requirements. And programming languages differ, of course. But still, for a given language, there’s typically a set of “core” requirements and best practices. These are aspects that the community of developers recognizes and accepts, even if they aren’t written down explicitly. In this book, we’re trying to provide you—someone who might not yet be aware of many of the practices in the Java community—with a set of best practices for clean code in Java.
As a beginner, your list of requirements for good Java code might be as short as this one:
- The code must compile.
- The output must be correct.
These items are about the functional correctness of your program, but they don’t tell much about the quality of your code. An experienced programmer cares about a lot more than that, and her checklist is much longer. She just needs a quick glance at a piece of code to detect flaws, bad naming, hard-to-test methods, inconsistencies, bad practices, and much more.
The aim of this book is to train your brain to internalize more checklist items, helping you on your way to becoming an experienced and professional programmer. Each of the items in this book represents such a checklist item.
Conventions Used in This Book
Throughout the book, we use a specific structure for explaining each checklist item. We call it “comparison,” and we zealously stick to it.
Each comparison has a catchy name. This helps you to memorize it for your mental checklist. Take a look at the table of contents—it acts as the checklist of this book. The name of a comparison makes it easier to talk to other people about what you’ve read. We’ve named the comparisons in a way that encourages you to consider them as a recommendation. You can also put “You should” in front of a comparison name—for example: You should avoid unnecessary comparisons. For the upcoming example, we selected the catchy name “Never Trust Your Input.”
Directly after the name, we’ll present a snippet of code and highlight a problem in it. This can be a block of several lines or just a single one, like this:
| | class HelloWorld { |
| | |
| | public static void main(String[] args) { |
| » | System.out.println("Hello " + args[0]); |
| | } |
| | } |
In these code snippets, we want to distract you as little as possible. That’s why we have to shorten the code a little bit to get to the essentials:
- We leave out import statements and package declarations. The downloadable code[7] contains those declarations, of course—it would not compile otherwise.
- We avoid visibility modifiers, such as public or private, unless they’re explicitly required.
Following the code snippet, we explain to you what the problem is. On the way, we provide references to further reading, such as JavaDoc, related items, or web pages.
Then, we show you the code of a solution and highlight the solution-specific parts.
| | class HelloWorld { |
| | |
| | public static void main(String[] arguments) { |
| » | if (isEmpty(arguments)) { |
| | return; |
| | } |
| | |
| » | System.out.println("Hello " + arguments[0]); |
| | } |
| | |
| » | private static boolean isEmpty(String[] array) { |
| | return (array == null) || (array.length == 0); |
| | } |
| | } |
Sometimes, there’s very little difference between the problem code and the solution. Sometimes, there’s a lot of difference. Either way, the snippets themselves should already teach you something—a certain style that helps you to produce better code. We deliberately keep each comparison on two pages. The left-hand side (or first page) shows the problem, and the right-hand side (or second page) shows the solution. This way, you can always compare both code snippets without having to flip pages back and forth. This makes it a lot easier to learn what an item is about. If you’re reading this book as a PDF with Adobe Reader, make sure you’ve enabled two-page view and that the cover page is shown—it’s almost like reading from the printed book.
Why Should I Learn This? There Are Static Code Analysis Tools…
You might be thinking that you already have static code analysis tools, such as Checkstyle,[8] FindBugs,[9] SpotBugs,[10] Error Prone,[11] and PMD,[12] that detect flaws in your code. So why should you keep reading this?
That’s true for some, but it’s not true for all the problems in this book. We’d love to see a tool that can automatically and correctly assess the concerns in your code. The existing tools are good, but they’re not perfect. Think of them as rigorous, intolerant, nitpicky robots that were taught a set of rules and seek any violation. They can’t understand that sometimes there are circumstances where you must violate a rule to improve the code. To use them successfully, they need to be fine-tuned, and that requires in-depth knowledge about code quality and the project at hand.[13] But even then, they can never beat an experienced programmer, although they can help so that some issues aren’t missed.
That’s good news, because it means that as an experienced programmer, your skills will be in high demand. Tools can check for a lot of things, but they often lack a detailed explanation for why something was detected. And they rarely show you how to solve a specific issue. Oftentimes, the solution to an issue isn’t apparent from the warning of a detection tool, and it’s rare that you can correct the code automatically. You have to do this manually, and that process is error prone—especially if you’re still learning Java. As a new programmer, the tools won’t guide you to a sensible correction. That’s where this book can help you. We’ll raise your awareness for common programming errors that many people make when learning Java.