GeoToolkit

Programming is an activity that requires a special set of cognitive skills. While the industry has developed processes and tools to ensure the quality of software artifacts, the act of writing code is a craft in itself. Developers pride themselves on the “big picture” results they achieve, but the activity of programming is definitely a humbling experience: It’s easy to introduce bugs, and regardless of whether I catch them right away or later in the pipeline, I hate to be reminded I am inherently flawed and have introduced a defect. For this article, I will focus on simple methods to avoid bugs, not before or after you write code, but while you write that code.

Leverage the Hints from the IDE

This one should be obvious to most programmers, but the reality is that the tools we use are a bit smarter than what we give them credit for. It’s easy to miss these hints. They are sometimes buried in build logs, drowned in a sea of flags, visually too subtle to attract our much-needed attention. Listen to your Integrated Development Environment (IDE)—it is telling you something.

One of the most obvious signs that something is up with your code is when the IDE tells you that you are not using a variable you introduced earlier in your code. You had some intent for this variable, but that intent got lost while working on some other aspect. There is certainly a bug lurking there.

Another useful alert is when the IDE detects that there is a logical path for a NullPointerException. Maybe the most common case is well taken care of, but there seems to be a road less-travelled to this ubiquitous exception.

The activity of writing code forces you to concentrate on the text you are typing while keeping a stack of other concerns in mind. This cognitive load is already heavy; I like to reduce it by removing ambiguities. The IDE will tell you when you are using the same variable name for an instance variable and a local variable. I don’t need to risk being confused about which one I am manipulating. I’ll follow my digital assistant’s advice and rename the local variable in question.

Break up Your Content

The brain can only keep so much information. And each coding window only shows you about 50 lines. When the code grows, so does the likelihood of bugs, just from not remembering details implemented a few invisible lines away. One simple technique to avoid such troubles is to break up the code. Keep the methods short. Ideally, a well-focused class shouldn’t have more than 200 lines. It’s not always possible, but where it is, you can avoid bugs when each class has only one responsibility. The class’ code itself is easy to review, and its function is easy to remember in other contexts. If you just wrote a large body of code in one class, it’s time to break it up into smaller pieces.

This is nothing new. When the metric of cyclomatic complexity was developed in 1976, its first applications tried to limit the complexity of each module, splitting them into smaller modules. These modules became easier to write, and easier to test, too. If the most likely place for defects is where complexity lies, reducing complexity automatically reduces the rate of defects.

It’s not just the height of your screen that matters when having “too much to code” might be “too much to cope.” The width matters, too. This is actually a classic source of bugs: a line goes beyond what’s visible without scrolling, meaning it’s not being looked at as often as other lines. Code reviewed less is more likely to be incorrect. Long lines are also bug candidates when overly confident IDEs autofill their content over the developer’s watchful eyes. The simple solution is to break up these long lines, for example, inserting carriage returns when they go over 120 characters. The IDE will often show you this limit graphically.

Use the Java Type System

Object-oriented programming is a great way to abstract sequential instructions into relationships and behaviors. The Java type system is quite powerful. When two pieces of code interact, the parameters of this interaction typically need to meet specific type requirements, so the compiler will prevent code being typed from using the wrong object type in the wrong context.

You can use this type checking to your advantage to reduce opportunities for bugs. Writing a program often requires code where mundane objects are being passed around—a collection of names, an Integer identifying a record, etc. If you inadvertently pass the wrong list of Strings, the compiler won’t be any help. Instead of passing List<String> or Integer, create your own objects, such as “NamesCollection” and “RecordId.” By forcing the passing of functional objects instead of generic ones, you will know immediately, as you type, that you just picked up the wrong collection or the wrong number.

Don’t Leave Your Code to Chance

I have seen many cases where two (or more) classes have the exact same name. They have different package names, but package names are hidden away at the very beginning of each class that uses another class. It’s a good idea to give classes unique names across your code base. This will make sure there is no ambiguity around which one a developer is using. Murphy’s law is not your friend—you will inevitably pick the wrong one otherwise.

The behavior of HashMaps may also be a source of hard-to-troubleshoot bugs. The Java Virtual Machine tends to optimize the behavior of HashMaps when the application load grows. What this means for developers is that you will observe one behavior during development, and a different behavior in production. To avoid this kind of head-scratching riddle, I have learned to use LinkedHashMaps even when not needed as they will always return entries in a consistent manner. This is a trick to use wisely: the performance cost of using LinkedHashMaps should be weighed against the risk of having to solve a problem that only happens in production.

Reuse Existing Code

At the end of the day, there is so much to keep track of, just writing code is doomed to produce bugs. The simplest way to avoid writing bugs is not write any code at all, and leverage some other battle-tested component instead.

Reusing code is the ultimate simplification technique, but I am not just talking about integrating other people’s work into your own software. The code you already have is the result of many refactorings. It has real-world experience you are missing (or that you forgot). Use the code you already have as your template. If the quality of your template is not what you need, refactor this code, then reuse it. There shouldn’t be in your program “two best patterns” to do the same thing.

As I implement a new feature, I typically look at similar code doing similar things: how classes, methods, and variables are (meaningfully) named, which properties and behaviors are exposed, how objects interact with each other, etc. In all the bodies of code I have maintained for several years, I have found that consistency is the easiest constraint to follow, to teach, and the one that brings the most benefits in terms of overall quality.