Deprecation

Every now and then, we find out our decisions from the past weren't the most elegant ones, limit us in unnecessary ways, or don't fit into the bigger picture anymore. This is a natural thing, as we move on and gather experience, we see our solutions in a different light - and we see how a problem could have been solved in other ways. In reflective moments we start thinking "If I had to do this again today, ...". This happens in personal life but also - for programmers - with code we have written.

In these situations, we face a tough decision: What we wish to do is to start changing all the code, upgrading it to our new and larger spectrum of wisdom, and if we we trigger-happy folks, we'd probably do just that. But on the other side, we know this might cause problems in other places using the code in all kinds of ways (some of them we might not even have envisioned). We realize we need a migration path, a workaround, a plan, communication, discussions and a time frame for all of this. Citing an earlier quote that programmers are lazy, this is the stuff we don't like to do; we'd rather just implement the change and then continue to do what we're best at: writing code to solve technical problems.

The programming world has a term for this: Breaking changes. What we usually break is backwards compatibility - software written against the version before our change will break when trying to use the newer one. And what programmers hate more than conceptually designing well-worked out migration plans is to have stuff broken. Not necessarily in the moment it happens but once they want or have to recompile, install or deploy (depending on what stage this break would surface in the technologies we use).

The compromise

• There is a quite impressive list of deprecated things in the Java programming language nowadays, and Sun also ships a guideline for deprecating.
  
• The PHP project introduced a so-called "error-level" named E_DEPRECATED in PHP 5.3.0 to get rid of design mistakes from the past, including magic quotes, register globals and call-time pass by reference.
  
• Bigger vendors usually guarantee to continue support for deprecated functionality for a limited span of time - Google gives one to three years, Microsoft's mainstream support phase extends over five years; smaller vendors and open-source projects usually have tighter schedules.
  
• Some thoughtful framework providers even provide migration tools.
  

A real-life example

<?php 
  raise('lang.MethodNotImplementedException', 'Deprecated', 'FtpConnection::get');
?>

Discussion

Extension methods

1. We deprecate an entire class or interface.
   
2. We deprecate one or more methods inside a class.
   
3. We deprecate a certain method signature.
   

<?php 
  // The old way
  $conn->put($local, '/'.$filename);
  
  // New way
  $conn->rootDir()->file($filename)->uploadFrom(new FileInputStream(new File($local)));
?>

<?php 
  // Declaration
  class DeprecatedFtpMethods extends Object {
    static function __static() {
      xp::extensions('peer.ftp.FtpConnection', __CLASS__);
    }
    
    public static function put(FtpConnection $self, $local, $remote) {
      $dir= $self->rootDir()->getDir(dirname($remote));
      $dir->file($remote)->uploadFrom(new FileInputStream(new File($local)));
      return TRUE;
    }
  }
  
  // Usage
  uses('...', 'xp.bclayers.ftp.DeprecatedFtpMethods');
  
  $conn->put(...); // Now calls extension method
?>

• Framework developers can remove deprecated methods instead of dragging them around for ages.
  
• Products' developers need to be explicit about using deprecated functionality and add the extension method classes to their uses() list.
  
• We can easily grep for sourecode using these BC layers instead of having to perform static code analysis or add logging to old methods.
  
• There is an incentive for upgrading - if not for the new features then at least for one guaranteed reason: extension methods are slower than their "real" counterparts.
  
• ...but most important: No complete refactoring of old code way down in the depths of an application!
  

Subscribe

You can subscribe to the XP framework's news by using RSS syndication.

Categories

Related

Find related articles by a search for «Deprecation».