How To Deprecate Things Like A Real Man. Or Woman.

So. You have this huge class doing complicated things with methods that take a bunch of arguments, and the author, for reasons obvious only to him, suddenly decided that he should deprecate the method that you’ve been using the most.

public class ReallyImportantClass {
    /**
     * @deprecated aMethodWithALotOfArguments has been deprecated.
     */
    @Deprecated
    public void aMethodWithALotOfArguments(String s, Long l, Integer i,
            Object ... args) {
    	// do some really complicated things here
    }

    public void aMethodWithALotOfArguments(String s) {
    	// do some really complicated things here
    }

    public void aMethodWithALotOfArguments(String s, Map m) {
    	// do some really complicated things here
    }

    public void aMethodWithALotOfArguments2(String enc, String s, Long l,
            Integer i, Object ... args) {
    	// do some really complicated things here
    }
}


Okay. Maybe that was a little exaggerated. But you have encountered that before, haven’t you? It’s bloody annoying, especially when the call to that deprecated method is buried deep inside another long method and I… don’t… care… one… iota… what your method is doing… I just want to replace your freakin method with its successor and move on to another thing. Very infuriating.

So, let’s be considerate to our fellow programmers, shall we? When deprecating a method, always tell your users these:

  1. Which method replaces the deprecated method–this is the least we could do!
  2. How to call the new method so you have the same effect as the old one. This is very important for people who don’t care what your method does and just want to make sure they won’t get bitten when they upgrade to the next version of your library, which no longer have the deprecated method. They need to know how to make their program still behave the same with the new method. This is not always possible, alas. java.lang.Thread.stop comes to mind. Then at least document the alternative approach, eh?
  3. If the users of your class are your teammates in the same project, document why you are deprecating the method.

Going back to the example:

    /**
     * @deprecated aMethodWithALotOfArguments has been deprecated
     * because it may not perform correctly under certain circumstances.
     * Please use aMethodWithALotOfArguments2 with "UTF-8" as the
     * first parameter to replace the call to this deprecated method.
     * @see ReallyImportantClass#aMethodWithALotOfArguments2(String, String, Long, Integer, Object[])
     */
    @Deprecated
    public void aMethodWithALotOfArguments(String s, Long l, Integer i, Object ... args) {
   	// do some really complicated things here
   }


The same goes for deprecating classes and fields. Let’s try to be more considerate to our fellow programmers!

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