Class Naming Scheme

[Berin Loritsch <bl...@apache.org>]

I am really wanting to help Axis in a meaningful way,
however this mindless exercise does need to be done
to make the API friendly and reduce duplication of
classes.  Below is my general philosophy regarding
class naming and API structure.  My credentials include
the Avalon Framework and Cocoon publishing framework.
I have been very good supporters of both of those
projects and have learned alot regarding coming up
with a scalable and workable API.  Please let's get
this discussion over with so we can get this part
behind us.


1) We should not have duplicatate classes in the same
   jar.  By that I mean classes that do essentially
   the same thing.  This code duplication leads to
   wasted effort as we try to maintain different
   copies of classes.  Classes that are functionally
   identical need to be identified (this goes beyond
   duplicate names BTW).  If a standard API includes
   a class that we are maintaining--but does not have
   everything we need, we should look into extending
   it.

2) The package hierarchy has to be the way everyone
   likes it.  Hopefully you have already taken care
   of it.  I won't spend any time on this effort unless
   I come accross something that doesn't make sense.
   One approach that works well (and it seems to be
   in practice) is that all similar components be in
   the same package (or sub package).  For example,
   all Handlers would be in the **.handler package.

3) Duplicate names are confusing--they should be avoided
   if at all possible.  The only exception to this rule
   that I think is acceptable is when we have Factories
   that have to dynamically look up and instantiate classes.
   Even then, there are more elegant ways to implement
   the factory patterns.

4) Regarding **.http.HTTPActionHandler vs. **.http.ActionHandler
   I prefer the name of the class to be unique regardless
   of whatever package it is in.  Honestly, if we have an
   HTTP specific ActionHandler, then I prefer the name to
   reflect that (HTTPActionHandler).  This is already in
   Axis BTW.

5) Componentization requires that you code your components to
   an interface.  Your work interface is the Role the component
   plays in the system.  Some people prefer to name their
   interfaces with an 'I' prefix--however this is not necessary,
   and is more elegant if the interface is the name of the
   Component in question (i.e. Handler is preferred to IHandler).

6) Abstract classes should be prefixed with the name "Abstract".
   In regards to Componentization, I am opposed to the practice
   of naming the abstract base class by the name of the Component.
   This practice stems from people who are used to C++ where
   interfaces are not available.  The issue I have with it is
   that new developers may think they can simply instantiate
   a class if they don't have an immediate feedback that a class
   is abstract.  Also, by having an Abstract base class with
   the prefix "Abstract" most developers will extend it rather
   than reimplement all the functionality required.  It is also
   a visual clue that new classes should "extend" it instead
   of "import" it.

7) Default implementations (or the basic implementation you include)
   should be marked as such.  Again, different projects have
   different guidelines and I work with either just as well.
   The Avalon project takes the approach of prefixing the class
   with the word "Default".  This approach takes advantage of
   the "Abstract" idiom and gives the message that any other
   implementations of a Component or class should behave similarly.
   The Cocoon project uses the "Impl" suffix in many cases (it
   is not entirely consistent).  The only thing I don't like about
   this idiom is that it implies that this class is "the"
   implementation.  Either way is fine with me--I just advocate
   being consistent.

8) All implementations of a Component (i.e. implementations
   of the interface) should have the name of the interface as
   the suffix.  Examples include "DefaultHandler", "HTTPActionHandler",
   "HTTPAuthHandler" (where "Handler" is the interface name).
   These classes are specializations of the Handler.  They all
   behave similarly to the system, but under the hood have specific
   purposes.