Use standard exceptions and don’t forget appropriate documentation

Take a look at this code. It compares two input Strings. The strings may represent values of different (!) datatypes as Strings. What do you think about this code?

public boolean areValuesEqual(String valueA, String valueB) {
       if (ObjectUtils.equals(valueA, valueB)) {
              if (isSameDatatype(valueA)) {
                     return true;
              } else {
                     throw new IllegalArgumentException(“some message”);
               }
        }
        return false;
 }

Well my first thought was a method called areValuesEqual should ONLY return true OR false. So instead of throwing an IllegalArgumentException why not just returning false? But there was the following Javadoc.

/** Returns <code>true</code> if the both given strings represent the same value defined by this
 * datatype. The String " 1" (a blank followed by the char '1') and "1" (just the char '1') are
 * equal if the datatype is an Integer, but will not be equal if the datatype is a String.
 * @throws IllegalArgumentException if one of the parameter values doesn't exist in the value
 *  set of this datatype.
 */

I have to mention that this method is part of the API of an software, which is in use by different customers. So throwing the IllegalArgumentException away would be an API break. Furthermore when we examine the javadoc we may recognize the similarity to the definition of the IllegalArgumentException. The IAE is “thrown to indicate that a method has been passed an illegal or inappropriate argument” [1]. This could totally happen within this method. If the entered parameters are of different datatypes they shouldn’t be compared. The illegal input has to result in an IllegalArgumentException. The calling methods should guarantee that no IllegalArgumentException arise by calling this methods with appropriate values or use a try/catch block in order to prevent the program to crash.

Ok so the right exception is called, but did you recognize an error in the piece of code? Well the method throws only an exception if the values are equal and isSameDatatype (valueA) returns false. But that’s not enough. What if the datatypes of the input values are not alike (illegal input) and ObjectUtils.equals(valueA, valueB) is true? It would return false instead of an IllegalArgumentException. The code should be looking more like this:

public boolean areValuesEqual(String valueA, String valueB) {
       if (isSameDatatype (valueA)) {
              if (ObjectUtils.equals(valueA, valueB)) {
                    return true;
               }
               return false;
        }else {
               throw new IllegalArgumentException(“some message”);
        }
 }

IllegalArgumentException is a standard exception. I thought a bit about specific exceptions. Java provides us the opportunity for specific exceptions. But why do programmers prefer more general exceptions. I think it’s just convenient to use standard exceptions. Programmers are familiar with them which make the code just easy to read. Whenever you think about creating a new Exception, ask yourself “Is there an existing (standard) exception which totally fulfill my needs?” If yes there is no need for a new one. And especially ask yourself “Will I use this newly created superspecific exception more than once?”. Remember we want to write great AND readable code. Therefore we usually long for code reuse. Exceptions are no exceptions thereby.

IllegalArgumentException is a standard exception which is often used and very known at programmers. And it just pretty much fulfilled all we could ask for in the presented code example. But remember it is always best to document your code. Whenever using exceptions also write why an exception may be thrown. With a clean Javadoc another developer won’t mistakenly remove that exception from the code.

References
[1] https://docs.oracle.com/javase/7/docs/api/java/lang/IllegalArgumentException.html

Read about how to use exceptions effectively
http://www.javaworld.com/article/2075476/core-java/exceptional-practices–part-1.html

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s