The curious histories of our deprecated methods

I've compiled a spreadsheet of all the deprecated methods I found in 2.8, and searched back for when they were added to the codebase and when they were deprecated.

Before we dive into the details, I'd like to make a few suggestions regarding deprecation. The @deprecated annotation currently takes a message String. This is a big improvement over having nothing, but I believe this could be structured even better. Good deprecated messages indicate the alternative that should be used. Great deprecated messages would indicate when the feature was deprecated and when it is expected to be removed. I think these three pieces of information should be codified as arguments to the @deprecated annotation.

  @deprecated(sinceVersion="2.8.0", removedAfter="2.9.0", insteadUse="method bar")
  def foo = ...

This would force library developers to commit to a deprecation policy as soon as they deprecate something, it would make library users more cognizant of just how fragile their deprecated methods are, and it would make it really easy to scan a library before a release to see which methods are due for removal.

Putting my aside aside, let's talk about the spreadsheet I made. If it says "2.6.0" that really means "on or before 2.6.0", as my analysis only goes back that far. I started writing it as "<=2.6.0", but that screwed up the sorts on the spreadsheet so I dumped it for just "2.6.0".

There are 10 things that have been deprecated since at least 2.6.0. These should be removed asap.

For stuff deprecated since then: 2 things were deprecated in 2.7.1, 15 things in 2.7.2 (one of these was added in 2.7.1), and 1 thing in 2.7.3. I guess these are up for discussion but I'd be in favor of removing them with prejudice.

More interestingly, 17 things have been deprecated in 2.8.0 that were only added in 2.8.0. These should also be removed asap. (One of these was a method added in 2.7.2, but placed inside a comment block with a note urging the reader to "enable this for 2.8.0!". Tragically, this method may never see the light of day.)

About half a dozen methods have been "deprecated" since 2.6.x. Unfortunately, they've only been @deprecated in a Scaladoc comment, so the compiler won't tell you you're using a deprecated method. Even though the intent to deprecate these methods has been around for a while, it would be unfair to remove them now because, as every schoolteacher and library writer should know, no one reads the test instructions or the documentation. (There are still two methods which are only deprecated in comments: pushAll on each of mutable.Stack and immutable.Stack.)

Finally, there were conflicting efforts to 1) move methods into more general traits or to take more general arguments and 2) deprecate certain methods. While both efforts are laudable, sometimes they cancel each other out. It is the case that methods from 2.7.x have both been made more general and deprecated in 2.8. In my opinion, such methods should be kept deprecated but made no more (and no less) general than they were in 2.7.x, under the principle that functionality that wasn't available in 2.7.x should not be added in a deprecated state. That merely encourages users to use new functionality that they won't be able to depend on in the future.

I have more comments, but they'll have to wait for another time.

Here's the link to the spreadsheet:

http://spreadsheets.google.com/ccc?key=0AqpDDf0Sr4EXdFNpeWo4eWthS3ctTGhmYXpRV3c1dEE&hl=en

--j