commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Michael A. Smith" <>
Subject Re: Deprecating and Refactoring
Date Mon, 17 Jun 2002 20:41:27 GMT
On Mon, 17 Jun 2002, Morgan Delagrange wrote:
> I don't have a problem with deprecation per se, but
> it's not a trivial event.  

as trivial as:

  @deprecated Use {@link Foo} instead.

> Deprecation is useful when you want to make a clean
> break from some older code in favor of some much
> better but incompatible code (many of the deprecated
> AWT classes probably fall into this category).
> But IMO using deprecation as a way to
> rename/reorganize classes or methods (unless those
> classes are _extremely_ confusing in their current
> state) can be bad practice.  One big problem is that,
> because deprecated classes are not maintained, it's
> typically only a matter of time before that class'
> dependencies get out of sync.  This means that the
> deprecated class may stop working or, even worse,
> require a developer to revisit it to clear up
> compilation problems.  If you can, you're better off
> just documenting any methods and classes that are not
> named optimally.

Well, your assumption here is that deprecated classes are not 
maintained.  While that may be the case in some places, I think not 
maintaining them is the "bad practice" not the act of deprecation.  

In some sense, your argument here seems backwards to me.  When renaming
or moving things, the deprecated method can simply pass the request
through to the new method -- there's really nothing to maintain, so your
argument doesn't hold much weight in my mind.  When doing some heavy
refactoring for major improvements but with incompatible code, there is
a much larger risk of non-maintenance on the deprecated classes, yet in
that case you support deprecation.

In any case, adding a @deprecated tag *is* just adding documentation.  
It's just a javadoc tag after all; no one is required to change anything
just because the compiler spits out a message saying "Hey, you're using
a deprecated API".

On the other hand, *removal* of deprecated methods/class or
*non-maintenance* of deprecated methods/classes are not trivial events.  
They potentially have a large impact on our "customers", the users of
commons code.  In which case, just a simple rename isn't really enough 
unless you make sure that the customers have *ample* time to adjust to 
the non-deprecated API on *their* schedule.  

That's why I made the following comment in another thread:

On Mon, 17 Jun 2002, Michael A. Smith wrote:
> Deprecating is just a way of saying its not the preferred mechanism for
> the functionality.  It doesn't necessarily mean we are going to remove
> them.  I'm not against deprecating the iterators (are there really 10?
> I didn't think there were that many), although I would be if we were
> planning on removing them.  Maybe after a few releases of deprecation we
> could *consider* removing them and plan for removal in a future release,
> but now is too soon.

Any existing classes should be maintained, even if deprecated, for the 
foreseeable future.


To unsubscribe, e-mail:   <>
For additional commands, e-mail: <>

View raw message