Four harmful Java idioms, and how to fix them

Rewrite convention and optimize your code for maintainability

By John O'Hanley, JavaWorld.com, 07/29/08

Idioms in any programming language help you get your bearings and provide structure when you start writing code. But, as John O'Hanley points out, some Java programming idioms are both widespread and harmful, having a negative influence on code maintainability. Read on if you're ready to break with convention, rewrite four harmful Java idioms, and optimize your code for maintainability.

Coding idioms exist to make life easier for programmers -- in particular for maintenance programmers, who are usually reading code produced by someone else. Coding conventions are fundamentally about showing compassion for these maintenance workers; the conventions you choose should allow them to read, understand, and use your code as quickly and as painlessly as possible. The more you optimize your coding style for the mental experience of those who will be maintaining your code, the more compassionate your code becomes, and the more quickly it will be understood.

Similarly, higher-level idioms (immutability and package structure, for example) aim to both improve the design and make code easier to understand. In fact, some might say that "improving the design" and "making the code easier to understand" are, in the end, one and the same thing.

In this article, you'll see that some popular idioms should be changed in favor of alternatives that are demonstrably more compassionate towards the reader. One might argue that any idioms that are already widespread should never be abandoned, simply because they are expected by most readers. However, reader expectations are only one part of the equation, and they shouldn't necessarily override all other considerations. The fundamental question should not be "Does the reader expected this?" but rather "How fast will the reader understand it?" I'll approach four different problematic -- but common! -- idioms in turn.

Local variables, method arguments, and fields: Which is which?

When trying to understand code, a reader often needs to answer a simple question: Where did this data come from? In particular, when trying to understand a method, a reader needs to know which items are local variables, which are fields, and which are method arguments. To exercise compassion for your reader, and to absolutely minimize the effort required to understand your code, it's likely best to use a simple naming convention to distinguish between these three cases.

Many organizations qualify field variables with this to distinguish them from other kinds of variables. That's good, but it doesn't go far enough: there should be a convention to distinguish method arguments as well. The logic that justifies naming conventions for fields also applies to method arguments, and for exactly the same reasons.

Listing 1 offers an example of an equals() method that does not distinguish between the three kinds of variables.

Listing 1. A method that doesn't distinguish between variable types

public boolean equals (Object arg) {
  if (! (arg instanceof Range)) return false;
  Range other = (Range) arg;
  return start.equals(other.start) && end.equals(other.end);
}

The French writer Marcel Proust was famous for analyzing human experience to microscopic levels. How would a modern-day Proust describe the experience of reading this equals() method? When you try to understand it, you experience a small amount of discomfort when you encounter start, because it's suddenly referenced out of the blue. Your brain hits a speed bump as it encounters something it hasn't seen before -- Uh oh, what's this? After a moment, through a tedious process of elimination (the length of which is proportional to the size of the method), you will eventually figure out that start is actually a field. The same sort of trivial and tedious reasoning is also needed to distinguish method arguments from other types of data.

Archived Discussions (Read only)

Subject

Forum migration complete By Athen

Forum migration update By Athen