• To begin with, there are a lot of them.
• They are represented using a mix of ints, longs and strings. Even the same id may be represented using different data types in different places.
• We’ve had bugs where an object with multiple ids has been put into a map using one of its ids as key and someone else tries to get it out using another id as key.
• Their names are sometimes confusingly similar.
• The same id may have multiple names, used intermixed.

Therefore, we’ve discussed various ways of getting a grip on the situation. One of the alternatives, which I think sounds rather good, is to use a separate class to represent each type of id.

For example, a User class doesn’t have a int userId field, but a UserId userId field. How UserId internally represents the id (perhaps as a long or string), is up to that class.

Some of the pros of this solution, from a Java perspective, are:

• When the id is used “out of context”, you don’t have to rely on variable naming to convey its meaning, you will get static type checking to help you.
• If you want to change the internal representation (int, long, etc), you only need to change a rather limited number of places instead of all over the system.
• You get an opportunity to create a suitable toString(), hashCode(), and or equals() implementation.
• You get a natural place for common convenience methods regarding the id, reducing the need for various “util classes” (which really are more procedural than object oriented).

The primary drawback that I can think of is that it generates a lot more small objects which may increase memory usage. But until it has been proven to be an actual problem in a specific case, I think that is a reasonable cost for the benefits above.

If you would like to read through the description and leave a comment or two I would be very grateful! Feel free to just add a comment or two in this document.

I’m using a fictional weather service as example. It does something along the lines of fetching the current weather data from a web service, parse it and extract relevant data, fetch some information about the current geographical location, and finally analyze them to provide the user with some interesting information about the weather.

Design A

The system is designed with the majority of the code as a set of completely independent modules which are joined together with a small amount of glue code.

Classes and modules tend to send primitive data or value objects to each other rather than intelligent classes. Modules tend to have none or very few dependencies. Re-use of modules is simplified because they can be used independently of each other.

Modules tend to be stateless with any state kept in the caller/glue code. External dependencies are kept as shallow as possible in the call/dependency tree.

The sequence of calls needed to perform something is encoded in the glue code rather than spread out in the system. It is up to the caller needs to know in which order to call modules. It delegates the execution of each step to the modules, but keeps control. The call stack will always remain rather short.

Each module can be unit tested in isolation and internal classes inside the modules do not have separate tests. The glue code is tested through integration tests that run end-to-end to verify that the system works. Unit tests often become easier to write because there is no need for mocking dependencies.

This approach is more “functional” in nature as modules tend to be stateless, get all required data as input and return the result as output.

Design B

The system is designed as a set of interacting, often stateful, modules which are joined together in a graph of dependencies.

One module often calls another module without providing all information necessary to complete a task, secure in the knowledge that the other module can obtain it. This is typically performed through injection of dependencies. Modules therefore often have multiple dependencies.

Modules are often stateful or depends on objects which are. External dependencies are often pushed as deep down the dependency tree as possible.

The sequence of calls needed to perform something is often spread out over a set of modules and partially encoded in the dependency setup. The caller can often call one or a few modules knowing they will in turn call others. The caller delegates not only the execution of tasks but also control to a large degree. The call stack will in the middle of execution be rather deep.

Each module is unit tested, typically with any dependencies replaced with stub/mock/fake instances. Integration tests ensure that the wiring of the modules is correct and that the system works together. There is little fundamental difference between tests on different levels.

This approach is perhaps more “object oriented” in nature where the system is divided into a set of stateful, intelligent objects that cooperate in generating the output.

Questions

I would appreciate any comments or input, such as your thoughts about:

• Which alternative you prefer? Which one do you most often use? Perhaps a hybrid?
• Under which circumstances is one better than the other?
• Are they good at different levels? E.g. method, class, component, or system level.
• Is there a “OO vs functional” difference, as I suggest?
• Is either of them easier to maintain than the other?
• Can they be described more clearly? What are they called?
• Have I gotten anything or everything completely wrong?

Feel free to enter any feedback or comments below.

Example

In the project I’m working on, I had a class called SelectedInstalledBase which represented the subset of products in a customer’s “installed base” selected by the user. (An “installed base” is this domain is all the products a customer has bought.)

That was fine until I wanted an inverted version of the selection, i.e. the installed base not selected (the “remaining installed base”). Then, it suddenly didn’t make much sense to create a remaining installed base of type SelectedInstalledBase. It also didn’t make sense to create a clone of SelectedInstalledBase named RemainingInstalledBase as they would be identical apart from the name.

The solution the problem was renaming SelectedInstalledBase to InstalledBaseIdentifier (because it represented the ids of the selection made by the user) and naming the variables to reflect the different cases, such as InstalledBaseIdentifier selectedInstalledBase and InstalledBaseIdentifier remainingInstalledBase.

In some cases I might have rewritten, changed, extended or simply misunderstood what he was saying, but these were my notes from the course, nevertheless.

• Doing TDD is like losing weight. You like having lost some weight, but not actually losing it.
• Taking really, really small TDD steps is useful when you’re unsure/confused about the code you are writing. That way you are at least moving forward.
• What kills productivity isn’t doing something slowly, but not doing it. I.e. when you switch to reading email, surfing the web, etc instead of working.
• Implementing a piece of code inside a test keeps your options open if you’re not sure about the future interface.
• Start writing the test which you expect to learn the most from.
• Most important, according to Kent: Writing a test is really telling a story about the code. Having that mindset helps you work out many other problems with testing.
• Deleting tests comes down to story telling – which tests do we need to tell the story about this code. (There is also a technical/coverage aspect, but it is of lower importance).
• When unsure about whether to clean something up or not – think about the amount of leverage it will give you. Worth it?
• When coding exploratory (without TDD), start TDD:ing when/if you don’t expect the code to die anymore, or when you think you’ve learned the most important lessons.
• In many cases: The more discussion, the less important the decision. Everyone agrees about the really important ones.
• Write code in a functional style, as it is more suitable for testing.
• Consider not using dependency injection as it makes TDD harder by encouraging a design where dependencies are spread out over the system. Instead, design many stand-alone modules which are unit tested individually without the need for mocked dependencies, then join them together in other classes which are tested through integration tests.
• Avoid abstact superclasses for unit test classes as they make the individual test classes harder to read.
• Duplication is often more okay in tests than in the production code because readability of tests is so important.
• For infrastructure-related setup code, @Rule can be used instead of inheritance in many cases.
• Write tests on the high and low level, but be weary of too many tests on the mid level. They tend to be more of a problem than help when refactoring.
• Kent: “I try not to have more tests than I need”
• Use one test class per fixture (i.e. set of test data). Name the classes after the fixture. That is how JUnit is designed and intended to be used.

One type of interface, which we might call separation interface, aims to separate different components. In this case, a component only exposes interfaces for its functionality but not the actual classes to make sure that clients aren’t too tightly coupled with the implementation. In this scenario, there is typically ever only a single implementation of the interface and both the interface and the implementation have the same author(s). Whenever you see a Interface/InterfaceImpl pair, you are most likely looking a this kind of interface use. This pattern is considered a best practice between components and systems, but rarely useful inside cohesive modules where classes naturally are more tightly coupled.

The other type of interface, let’s call it extension interface, is intended to represent an ability than an object can have. Here, multiple implementations of the interface exists and the client can choose the implementation that best suites his or her needs. A component often defines an interface on which it depends in order to allow implementations to be added at a later time. Often, the author of the interface is not even the same as the ones who create the implementations. This type of interfaces (together with regular inheritance) are the foundation of polymorphism. Iterable or Comparator are typical examples.

Quite possibly, there are other types of interfaces as well. Feel free to comment on the issue.

Some people who use test-driven development, also use tools that allow the to peek into classes and read private variables. That is an efficient way to ensure that some method altered the state of the object in the expected way.

However, as Michael pointed out, by doing so they miss the point of test-driven development. Test-driven development adds constraints. It does that in order to force developers to design their code better. (TDD is about design, not testing — remember?) By peeking into classes, one effectively removes one constraint added by TDD, and thereby removing much of the benefit of TDD.

To quickly summarize, the series looks as follows:

1. Throwing Exceptions
2. Using Assertions
3. Catching Exceptions (this one)
4. Logging Exceptions

The information in this post is divided into two parts: when to catch, and how to catch.

When to catch

Here are some guidelines on when to catch exceptions and when to let them propagate up through the call stack.

Catch only exceptions you know how to handle, and be specific

Provide a general catch-all

How to catch

When you catch an exception, make sure to do it the right way.

Do not suppress or ignore exceptions

Always clean up after yourself

Declarative exception handling

Next week, the final episode of the series will be published, so be sure to check back. If you have any comments, please provide them below!

A quick summary of posts in this series:

1. Throwing Exceptions
2. Using Assertions (this one)
3. Catching Exceptions
4. Logging Exceptions

Guidelines for assertions

An assertion is code that’s used during development that allows a program to check itself as it runs. They are used much in the same spirit as unit tests, but spread out in the actual program code. It is a statement placed to indicate that the developer thinks that some predicate is always true at that place.

Use assertions for conditions that should never occur

Use a barricades to distinguish between assertions and exceptions

Don’t put executable code into assertions.

For highly robust code, assert and then handle the error any way

Assertions in Java

For those unfamiliar with assertions, I’ll give a quick summary. Java provides the keyword assert since version 1.4. It throws a java.lang.AssertionError when it fails, and has the following syntax:

assert expression : "error message shown if expression is false";

Where expression is any boolean expression which should always be true at the point of the assertion. For example, this variable should always be greater than 0, or that collection should always be empty.

To enable assertions when running a program, use the Java VM -ea (or -enableassertions) switch. Assertions are always compiled in, but without this switch, the assertions are ignored by the virtual machine.

Tune in next week for guidelines for catching exceptions! And please do write any comments or questions you might have below.

The series will cover what I think is a good and sound strategy for handling exceptions and errors in your application.

It is written with Java in mind, but is applicable to most languages which feature exceptions.

A quick summary of the coming posts:

1. Throwing Exceptions (this one)
2. Using Assertions
3. Catching Exceptions
4. Logging Exceptions

Let’s get started!

General

First, we’ll go through some things which apply to all types of exceptions.

Always preserve the stack trace

Never use exceptions for flow control

Provide enough context

Next, we’ll discuss checked and unchecked exceptions, and when to use them.

Checked exceptions

A checked exception is a Java concept which means an exception which is specified in a method’s signature. It is a way for the designer to tell the client of a method what might go wrong, so that the client can prepare accordingly.

Throw a checked exception if a method can’t fulfill it’s contract

Make your exceptions part of your contract

Never let implementation-specific exceptions escalate to the higher layers

Unchecked exceptions

Unchecked exceptions are all other exceptions, which are “unforeseen”.

Prefer unchecked exceptions for all programming errors

If the client cannot do anything useful, then make the exception unchecked

Feel free to provide any comments or thoughts below, and check back in a week for the next episode!

I’m getting frustrated by people I talk to who seem to misunderstand the whole point of agile software development (IMHO).

Different ways of reducing risk

The point with agile, as far as I understand, is to reduce risk and thereby costs by postponing decisions until we have as much information as possible. In older waterfall processes, pretty much everything was decided upfront. That wasn’t because people thought it was so much fun to decide everything up front, but because they believed it to be the best way to reduce risk and cost. Because a bug found just before delivery is much more costly than one found earlier.

Agile, on the other hand, tries to use development practices which enable us to postpone decisions, practices which makes the system easy to change even later in the development process. Thus, the code you write should have two qualities:

• doesn’t force you into making unnecessary decisions, and
• be easy to change.

How to reduce risk the agile way

Quotes such as “You Ain't Gonna Need It” (YAGNI) and “Do The Simplest Thing That Could Possibly Work” (DTST) emphasize the first part — not making premature decisions. But while you can typically find people talking about the second part too, it doesn’t nearly get as much attention in people minds as the first one. Most likely simply because it’s not included in the name, in the mantra. I guess “You Aren’t Gonna Need It, But Do Not Forget To Make Sure Your Code Is Flexible” just doesn’t stick as easily.

Actually ensuring that your code is easy to change requires some work — especially while trying to avoid making premature decisions! It means using things like table driven code and putting abstractions in code an meta-data in configuration. It means thinking about what things are likely to change, and what things are not. It means not assuming too much, since you never know how things are going to be used in the future.

Where many people misunderstand agile

Rules and practices are good, but they are just the means to an end. I find that too many people interpret the agile mantras of YAGNI and DTST too literally. They create solutions which are “simple” and “works” and only includes “what’s needed”.

However, the next day, or next month, when requirements and expectations have changed (as they no doubt will) these solutions prove to be hard to adapt to the new situation. That’s because their developers forgot about the second part, making the system easy to change! And I believe forgetting that is forgetting the very core of what agile is about!

You agree? Got another opinion? How do you ensure you’re code is easy to change?

Joshua Kerievsky introduced the term Creation Method for these kinds of methods. The GOF pattern Factory Method is similar as it includes a subset of all possible Creation Methods.

So, how does a Creation Method differ from a constructor, semantically? When should one use one or the other?

Is computation required?

I tend to use a Creation Methods when the instance creation requires much computation. In one sense, it is very similar to when to use properties and when to use Get-methods in VB/C#.

Possibly, a Creation Method which does a lot should be seen as a separate responsibility and moved to a a separate Factory class. This is similar to what Joshua Kerievsky discusses in Encapsulate Classes with Factory, that some developers might not like having a class which has a Factory responsibility as well as its normal responsibility. In the end, I guess it’s a matter of taste.

Do you actually get a new object?

A Creation Method may be used when there is a finite set of possible objects to create. In such a case, a well named Creation Method may indicate that you cannot actually create a new object, but rather get one of the already defined.

An example would be the Java class Charset. There is a limited number of possible charsets (or at least number of charsets the system will understand), and therefore it does not provide a public constructor, but rather uses the method forName(String). You would use the following code to create a Charset object.

Charset c = Charset.forName("ISO-8859-1");

Other reasons

Another reason to use a Creation Method could be to hide the fact that it’s actually a (private) subclass which is being instantiated. In other words, that the Creation Method is actually a true Factory Method. See for instance the Money example in Kent Beck’s Test-Driven evelopment.

You’ve got more ideas on what differs Creation Methods and constructors? Post a comment.

Summary of coupling

Steve McConnell in Code Complete describes coupling as follows.

Coupling describes how tightly a class or routine is related to other classes or routines. The goal is to create classes and routines with small, direct, visible, and flexible relations to other classes and routines, which is known as “loose coupling”.

McConnell furthermore lists a number of different types of coupling, some of which are better than other.

• Simple-data-parameter coupling: All data passed between A and B are of primitive data types and passed through parameter lists. This kind of coupling is normal and acceptable.
• Simple-object coupling: A instantiates an object of type B. This kind is also fine.
• Object-parameter coupling: A requires B to send it an object of type C. This type is tighter since it requires B to know of C.
• Semantic coupling: A makes use of, not some syntactic element of B, but knowledge of its inner workings. Should be avoided.

Dependency injection to simplify testing

So, loose coupling is definitely good as it makes the system easier to work with. However, when I read one of Jeremy Miller's excellent posts I started thinking. He suggests using dependency injection to simplify testing in some cases, which to me seems to be creating tighter coupling within the system.

More specifically, the problem he describes is as follows. A class ClassUnderTest internally creates an object of type Dependency. However, if it is hard to create a new instance of Dependency equal to the first one (e.g. a datetime object representing “now”), ClassUnderTest becomes very difficult to test.

When the unit test wants to create a copy of the the hard-to-reproduce-object Dependency to compare with ClassUnderTest‘s Dependency instance, a non-equal instance is created (the system clock has changed) and the test fails.

The solution is to provide the object under test with either:

• the Dependency object in question itself, or
• an object which provides ClassUnderTest with the wanted Dependency instance.

I agree with this completely. In fact, I’ve had the problem a number of times myself, and solved it successfully this very way.

In terms of coupling

With respect to coupling, the case is that before we add the test (let’s assume we’re testing legacy code) we have simple-object coupling, since ClassUnderTest creates another object Dependency. However, when we test ClassUnderTest we want to create another object of the same type as Dependency equal to the one ClassUnderTest created.

As noted above, the solution is dependency injection — to provide ClassUnderTest with Dependency, either directly or indirectly. That way, we have the possibility to get hold of Dependency to perform the assertion in question. In terms of coupling however, this changes the coupling to be of type object-parameter coupling which is considered tighter than the type of coupling we had before.

A counter argument

Thinking about this, I thought that maybe the key here is that to test ClassUnderTest in the first case, the test would need to be semantically coupled to ClassUnderTest because it would have to know what kind of Dependency object it created internally (“now” vs any other datetime) and try to recreate it in some clever way. So we actually replace semantic coupling with object-parameter coupling — an improvement.

The counter argument (to the counter argument) is that without the test code, we would have no need to create such an object and there would be no semantic coupling in the first place. Thus, writing the test tightens the coupling in the system.

The question

Am I missing anything, or is this an example of where designing for testability actually leads to worse (as in more complex and more tightly coupled) design? Or am I just getting lost completely in theory? Maybe this slightly tighter coupling is nothing compared to what we gain from having a good and simple unit test in place.

The problem was that instead of thinking about what functionality I actually needed, I just assumed that since I was going to measure time I needed a regular stop watch. Thus, the first version of my timer had the operations start, pause, stop and reset, where reset was only available when the timer was stopped.

After a while I realized I was pressing the sequence stop-reset-start a lot of times. I did it every time a task was finished and I was about to start with a new one. So to make my life easier I added restart which did just that.

After using it even more I realized that restart now actually was the only button I was pushing. Therefore, I simply removed all other buttons than restart (which was renamed reset).

The result is a very simple timer. It auto-starts and is then always running. Thus, no need for start or stop. That’s great for measuring time while working, because real time doesn’t stop. I always spend time doing something. The only thing I can do with my time is divide it into chunks of time which I spend doing different tasks. That is exactly what my reset button allows me to do — tell where one such chunk ends and the next starts.

I’m actually very satisfied with the result. What is rather funny about this whole thing is that although I first thought I needed “just a simple stop watch”, my need was in fact slightly different and even simpler.

P.S. If you want to use the timer, it’s available at http://timer.henko.net/. However, it currently assumes Central European Time (+1). Time is also only shown in hours, since that is how I enter time in my time reporting tool.

While evolving a design is good and nice one has to remember that even though big design up front might not be a good idea, all the hard design work still needs to be done at some point. Otherwise you’ll just end up with a big piece of garbage. Therefore, while starting with a story or use case, do take time and think it through and answer a couple of questions for yourself (not an exhaustive list).

• What is the goal of the story?
• In what ways can we solve this?
• How does these solutions fit into the current system?
• What are the pros and cons of these solutions?
• What are the larger problems (if any)?

However, while thinking about all this, don’t try to work all the details out, they will sort themselves out while coding. More importantly, don’t commit to any of the design alternatives you come up with. The important part is thinking the problem through thoroughly. A quote from David Eisenhower sums this up nicely:

In preparing for battle I have always found that plans are useless, but planning is indispensable.

Steve McConnell in the second edition of Code Complete, describes how while he was writing the first edition, design zealots argued for BDUF, and as he was writing the second, some software swamis instead argued for no initial design at all. He says:

In ten years the pendulum has swung from “design everything” to “design nothing”. But the alternative to BDUF isn’t no design up front, it’s a Little Design Up Front (LDUF) or Enough Design Up Front — ENUF.

Another take on this is to make the decision in the Last Responsible Moment, described by Jeremy Miller in one of his articles.

The key is to make decisions as late as you can responsibly wait because that is the point at which you have the most information on which to base the decision. In software design it means you forgo creating generalized solutions or class structures until you know that they’re justified or necessary.

However, one might not use this advice to justify not designing at all. The key here is that you don’t commit to a certain design (i.e. make the decision) until the last possible minute, but you still consider the alternatives — which of course requires you to research and actually think about them!

1. It says that while all tests pass, you’re not allowed to add new functionality. To do that, you have to add a new test which fails because of the lack of the wanted functionality.
2. Then you make that test pass in the simplest way you can imagine. In fact, while you have a test which fails, you’re allowed to do practically anything (possibly except cardinal sins) to make it pass.
3. After you’ve made it pass, you can refactor all you want to clean up the existing code, including the lines you just wrote.

This is the rhythm of TDD, which is often called red/green/refactor, as a reference to the color of the progress bar most unit testing interfaces use when test fail and pass.

Anyway, back to the eye-opening experience. As an example, lets use the following test, asserting that a method for calculating the sum of two integers is correct.

public void testSum() {
    assertEquals(8, sum(3, 5));
}

The simplest way I can imagine to make this test pass is the following code is just faking the implementation.

public int sum(int augend, int addend) {
    return 8;
}

Now, this really feels bad. We know that returning 8 is not a correct solution for all possible parameter values. On the other hand, the test is passing, which is my proof of that the program works. Nevertheless, just faking out the implementation feels like cheating. No matter how many more tests we write for this function we could always just continue faking it by making another special case, ending up with a gigantic switch statement rather than the real and much simpler function (I leave finding the correct function as an exercise for the reader ).

Now comes what for me was an eye-opener. Kent Beck in his book Test-Driven Development describes how to solve this problem nicely. He notices that there is duplication between the test and the implementation; not duplication of logic, but duplication of data. The duplication is also not explicit, but implicit. What return 8; really stands for is return 3+5;. And it is rather obvious to us that 3 and 5 really are the same numbers which are given as parameters to the sum() function in the test. In other words, the numbers 3 and 5 are duplicated.

To avoid this and remove the duplication, we have to make the function somehow reference the values in the test. In our case, this turns out to be very simple, as they are given to the method as parameters. We refactor the method as follows, and the duplication is gone.

public int sum(int augend, int addend) {
    return augend + addend;
}

Now look and behold. By removing the duplication, we also made the function work as we wanted.

Lets think again about the rhythm of TDD. Since the test passed with our first return 8; implementation, we were at green bar (all tests passed). And when we’ve got a green bar, TDD only allows us to refactor the code, not add new functionality. Now, one can argue that the change made to the implementation (changing 8 to augend + addend) wasn’t a semantics preserving refactoring at all, but rather adding new functionality. To answer this, let’s recap on perhaps the most well known definition of refactoring, namely from Martin Fowlers book Refactoring.

A change made to the internal structure of software to make it easier to understand and cheaper to modify without changing its observable behavior.

So, in fact, practically all refactorings change the exact behavior of the code, just not the type we are interested in which is observable behavior. And when we’re talking Test-Driven Development, what you don’t have tests for, you can’t observe. Thus, the modification we made was not changing any observable (i.e. tested) behavior, just untested and therefore invisible behavior.

This might seem to you as either fooling oneself, or as an elegant solution to the problem. I put my vote on the latter.

Two ways to see it

Some say that it should be done using the instanceof operator, like this.

public boolean equals(Object obj) {
    if (obj instanceof MyClass) {
        MyClass that = (MyClass) obj;
        // compare this and that
    } else {
        return false;
    }
}

Other says that it should be done by comparing the exact classes of the two objects, like this.

public boolean equals(Object obj) {
    if (obj != null && obj.getClass() == this.getClass()) {
        MyClass that = (MyClass) obj;
        // compare this and that
    } else {
        return false;
    }
}

The difference lies in how they treat subclasses. As instanceof returns true if obj is of the same class or any subclass, it will allow subclasses to be considered semantically identical to their superclasses. Comparing the result of getClass() on both objects will require that they are of exactly the same class. Using that method, no subclass can ever be semantically equal to its superclass.

To understand why this difference matters, it is important to remember one of the requirements Java has on any implementation of equals(); the equality relation must be symmetrical. In other words, for any objects a and b the expression a.equals(b) may return true if and only if b.equals(a) also does.

Because of this, the getClass() camp argues that since we can’t predict how subclasses might want to implement equals(), we better implement equals() in such a way that it only compares objects of the same class. That way a subclass can safely override and implement equals() any way they want. For example, a subclass might have additional fields which it wants to use in the equality comparison. Otherwise we might end up in a situation where e.g. the superclass says that is equal to the subclass but not the other way around.

The argument from the instanceof proponents is that not allowing a subclass to be considered equal breaks the notion of polymorphism. It also violates the Liskov substitution principle as well as the principle of least astonishment.

How I see it

Okay, enough with the summary. Now I’ll throw my own two cents in.

I think this whole question pretty much falls apart if we just make a better distinction between interface and implementation. An interface decides what a method is supposed to do, while a particular implementation knows how to do it. In other words, it is up to the interface to define what equality means for that interface. Being separated from its implementation(s), the interface must therefore define equals() in terms of comparisons of its own members. Thus, it cannot require the other object to “be of the same class” without having inappropriate knowledge about at least one of its implementations.

One problem is that a class in Java is somewhat ambiguous as it both has an interface and provides an implementation for it. This makes the interface more implicit. If you think it makes things clearer, extract an interface from your superclass and let it define (through documentation and unit tests) the exact behavior of the implementation. Then implement that exact behavior in any way you see fit in your class.

Example: Collections in Java

A good example of how things should work is the collections framework in Java. If we look at the documentation for the equals() method of e.g. the Set interface, we see the following. Pay special attention to the last sentence.

Returns true if the specified object is also a set, the two sets have the same size, and every member of the specified set is contained in this set (or equivalently, every member of this set is contained in the specified set). This definition ensures that the equals method works properly across different implementations of the set interface.

This behavior is defined by the interface Set. It is then implemented in the abstract class AbstractSet which is in turn extended by HashSet and TreeSet. None of the two subclasses override equals().

Example: Employees and Managers

In a blog entry, Cay Horstmann uses another example. However, he is arguing for using getClass() rather than instanceof. His example includes a class hierarchy where we have an Employee class as the base and then a Manager class which extends Employee by adding a bonus field. Expressing the example in code, it would look something like below.

public Employee {
    public boolean equals(Object other) {
        if (!(other instanceof Employee)) return false;
        // cast other to Employee and compare fields
        // ...
    }
}

public Manager extends Employee {
    public boolean equals(Object other) {
        if (!super.equals(other)) return false;
        // cast other to Manager and compare fields
        return bonus == ((Manager)other).bonus;
    }
}

In other words, the subclass Manager changes the meaning of equality it inherited from its superclass Employee. Is this a sensible thing to do? As you might guess, I would say no. We (hopefully) decided when we wrote Employee that there was a given way to uniquely identify any specific employee. That might have been an employee id, combination of first name and last name, or any other combination of Employee members. For sake of discussion, let us say we compare the values of the function getId(). Being an Employee itself, what reason would Manager have to change this definition? To check if two Manager objects have the same id but different values for the field bonus? Well, if we do have two such objects, then that is the problem. We shouldn’t have allowed them exist at the same time. The job of equals() is not to guard us from having corrupt data in our model!

Final thoughts

If a subclass truly has to override equals() to provide a semantically different implementation of equals() it might instead be a sign of that the subclass perhaps should not be a subclass after all. A subclass is supposed to extend or alter the behavior of a superclass or implement the behavior of an interface, but always doing so within the boundaries of all inherited interfaces.

One way to make sure subclasses does not break the contract is to make the equals() method in the superclass final. However, I think that is just overly protective. There could be a valid reason for wanting to override the equals() and still preserve its semantics. Performance optimization could be one such reason.

Thus, in my humble opinion, the correct way to implement equals() is as follows.

public boolean equals(Object obj) {
    if (obj instanceof MyInterface) {
        MyInterface that = (MyInterface) obj;
        // compare public members of this and that
    } else {
        return false;
    }
}

However, my opinion might not be the same as yours, and your opinion might not be the same as mine (for symmetry purposes ). If you happen to have another opinion, feel free to comment or trackback!

Thinking to little

To some degree, programming is just mechanical work. We know what we want the computer to do, and we just need to write down the instructions. However, although we normally know what we want the computer to do, we don’t necessarily know the best way to do it. Figuring out a good way to do this is what programming is all about.

Unfortunately, the simplest solution is not necessarily the first one that comes into our minds. In fact, there seems to be an inverse proportionality between the complexity of a solutions and the time it took to reach it. Thus, simple solutions tend to take longer time and require more thought to find.

That makes it all seem very simple, right? The more you think, the better chance you have of reaching a good solution. Perfect! Then you could stop reading right now, and just spend some more time thinking. Right?

Thinking too much

Well, not quite. This is the time where programmers tend to get carried away. They get too eager, too ambitious. Programmers like to write complex code. They want to create the Perfect System™, reach design nirvana. There is something very satisfying in designing those perfect systems; extremely flexible with intricate interaction, beautiful class hierarchies, perfect cohesion and so little coupling that you have to use a magnifying glass to see it.

Not only that, W.E. Boebert, designer of an autopilot that ran for 15+ years without an in-flight anomaly, suggested that education also is a factor in programmers desire for design complexity.

I laid full blame […] on CS faculty who either knew nothing other than operating systems or held OS designs up as the ultimate paradigm of software. So CS students and new grad software engineers came out thinking that an autopilot should look like Unix.

So when you recognize those feelings inside you, it is time to stop and take a deep breath.

Doing the right thing

Most likely what we need right now is not the Perfect System™. Most likely we need a simpler, less complex system. While this might sound boring, it is pretty much almost the truth. I’m sorry. For some inspiration, read those words of wisdom from Queen Christina of Sweden, freely translated by me:

Greatness lies not in doing what one wants, but wanting what one should.

But come on you might say, why not build the perfect system? After all, if we do build a perfect system, it’s not that anyone is going to complain, right? Well, no. Chances are however that you’re not going to reach the perfect system. It is much more likely that we end up with a system which is not quite what you intended, overly complex with a class hierarchy with more levels than a Nintendo game. And while it can handle any future change you could ever anticipate, still doesn’t do exactly that we need right now. Without doubt you have spent way more time than can be justified and it still doesn’t work. Of cause, there are exceptions, and I might be exaggerating just a bit, but you get the general idea.

Extreme Programming stresses among other good habits the importance of, and time gain one gets from, not writing an overly complex solution in their first design rule:

Always do the simplest thing that could possibly work.

Benefits of simplicity

The saying goes that “less is more”, and this is very true when it comes to software design. By keeping our system as simple as we can we gain one very important quality; it makes our system easier to understand. Kernighan and Plauger wrote in 1978 as the first rule in their classic programming book Elements of Programming Style something which still, thirty years later is as true as ever.

Write clearly – don’t be too clever.

Actually, as long as it is syntactically correct, a computer has no problem figuring out what you mean no matter how the code is structured. The same is certainly not true for humans, however. Therefore, don’t write code for computers, they don’t care how it looks anyway. Write code for yourself and for your fellow co-developers – they certainly do care. And believe it or not, most of us actually have a limitation for how many layers of abstraction and indirection we can handle before exploding.

Another good reason to avoid complex solutions is that it generally is harder to debug programs than to write them. So, put somewhat jokingly, if you are as smart as you ever can when you write the code, how can you have any hope of ever being able to debug it?

I’ll sum up with the words of C. A. R. Hoarse, brittish computer scientist, perhaps most famous for developing the quicksort algorithm.

There are two ways of constructing a software design: One way is to make it so simple that there are obviously no deficiencies, and the other way is to make it so complicated that there are no obvious deficiencies. The first method is far more difficult.

Which way are you constructing your designs?