An API is made up of not only code, but also documentation. Imagine the Java JDK without the associated JavaDocs – would it still be as popular or useful? Of course not. In fact without the provided documentation and JavaDoc tool to generate more documentation, the Java language probably would not have been anywhere near as successful as it is.

So while you can enforce many constraints and cover many issues at a code level, there are some issues that are better dealt with at the documentation level. We see comments like “if you pass ‘X’ to this method, the result is undefined”. Perfectly legitimate to say this if that is true of the nature of the code – mathematical algorithms are often dealt with this way.

But now that I have gone to the effort to say this about my method, what happens if someone does pass ‘X’ to my method? Do I need to handle that situation? Should I just throw an exception? If I do nothing, and my code fails gracefully or crashes horribly, is it a bug in my code?

I propose that in fact as a client, it is necessary to comply with the documented API just as much as you comply with the coded API.

Here is an example. Suppose, you are writing some code and you choose to make use of a class from the JDK core classes. You take a quick look at the JavaDocs to make sure you know what you are doing and off you go. You are an agilist so you also write a thorough set of unit tests and make an effort to cover edge cases and corner conditions. On one of these corner conditions you notice the test is failing. You look at the your logging output and see that the method you are calling from the JDK is throwing a runtime exception. You check the parameter values being passed using your favorite debugger and see that the value makes sense to you. You then go back to the JavaDocs and notice that it mentions something about certain values not being valid and that an undefined runtime exception is thrown when those values are passed. At this point you have a choice, change your code to work with the API or complain that the JDK has a bug in it. Of course you change your code – I am not saying there are not bugs in the JDK, but you should consider yourself unlucky if you actually stumble across one.

So if you are writing an API, go ahead and write code defensively, but don’t kill yourself to code against every possible asinine value someone might try to pass to you. If your code interface is designed nicely and you write good documentation and you write a comprehensive set of unit tests, as far as I am concerenced, you are pretty much off the hook. Don’t waste time and lines of code defending against obvious bugs in your client’s code. Besides, if you have enough time to write code to defend against bugs in other people’s code as well as your own, you are probably on a dead end project and are destined to be looking for work soon anyway.

I see this on a regular basis. Engineers who get caught up in the whole defensive coding idea, or test driven development. Not that either concept is bad, but when the first 30 lines of every method are sanity checks for parameters than you should maybe consider how you are spending your productive hours. And don’t get me started about when I see this in non-public methods – really, you can’t trust your own code to pass you the right values?