Deprecating and Refactoring

[Jonathan Carlson <jo...@yahoo.com>]

Someone in a Collections thread previously expressed
concern over deprecating some things that might be used in
production code.  What's wrong with that?

The whole purpose of deprecation is to allow production
code to keep running while informing new development that
they are treading on old territory.  These utilities will
eventually become bloated and difficult to learn if the
commiters are afraid of deprecating old code when better
techniques come up.

My 2 cents,

Jonathan

=====
Jonathan Carlson
joncrlsn@users.sf.net
Minneapolis, Minnesota

__________________________________________________
Do You Yahoo!?
Yahoo! - Official partner of 2002 FIFA World Cup
http://fifaworldcup.yahoo.com

--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: Deprecating and Refactoring

["Michael A. Smith" <ma...@apache.org>]

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.

regards,
michael


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: Deprecating and Refactoring

[Morgan Delagrange <md...@yahoo.com>]

Hey Jonathan,

I don't have a problem with deprecation per se, but
it's not a trivial event.  

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.

- Morgan


--- Jonathan Carlson <jo...@yahoo.com> wrote:
> Someone in a Collections thread previously expressed
> concern over deprecating some things that might be
> used in
> production code.  What's wrong with that?
> 
> The whole purpose of deprecation is to allow
> production
> code to keep running while informing new development
> that
> they are treading on old territory.  These utilities
> will
> eventually become bloated and difficult to learn if
> the
> commiters are afraid of deprecating old code when
> better
> techniques come up.
> 
> My 2 cents,
> 
> Jonathan
> 
> =====
> Jonathan Carlson
> joncrlsn@users.sf.net
> Minneapolis, Minnesota
> 
> __________________________________________________
> Do You Yahoo!?
> Yahoo! - Official partner of 2002 FIFA World Cup
> http://fifaworldcup.yahoo.com
> 
> --
> To unsubscribe, e-mail:  
> <ma...@jakarta.apache.org>
> For additional commands, e-mail:
> <ma...@jakarta.apache.org>
> 


=====
Morgan Delagrange
http://jakarta.apache.org/taglibs
http://jakarta.apache.org/commons
http://axion.tigris.org

__________________________________________________
Do You Yahoo!?
Yahoo! - Official partner of 2002 FIFA World Cup
http://fifaworldcup.yahoo.com

--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>