Introduction
============

This document defines rules for naming classes and interfaces that allow a common style for gvSIG components to be maintained.

The importance of consistency in naming is obvious if one considers a complete Javadoc implementation. From the point of view of the reader, using a variety of naming conventions would create confusion and complicate the understanding of the component.


Criteria to follow
==================

Use of prefixes and suffixes in general
---------------------------------------

The use of prefixes and/or suffixes in the names of classes and interfaces is usually a means of providing information about their nature and/or task. For example they can be used to denote a pattern, or a role within a pattern (eg the suffix Factory). At other times, it is necessary to use them if the appropriate name has already been assigned. This is the case of the prefixes and suffixes that are described below. 

As a general rule:

* Only use a prefix or suffix when you can't use the simple name (usually because it is being used by another class or interface).


Using the prefix "Abstract"
---------------------------

* Only to be used for classes, **not interfaces**.
* The class must be abstract and implement an interface.
* Only used when the interface being implemented has the same name.

Example::

   public interface List {}
   public abstract class AbstractList extends AbstractCollection implements List {}


Using the prefix *"I"*
----------------------

* It is recommended that this prefix **not be used**. 

  Typically, the interfaces are the visible part of a component model. 
  They usually represent entities and concepts from the business or domain and therefore it 
  is recommended that the same names be used as in the business.


Using the prefix *"Default"*
----------------------------

* Can't be an abstract class.
* A default implementation of an interface or an abstract class.
* The implementation should be sufficient, but not necessarily complete.
* There may be alternative implementations of this class.

Example::

   public interface ListModel {}
   public abstract class AbstractListModel implements ListModel, Serializable {}
   public class DefaultListModel extends AbstractListModel {}


Using the prefix *"Base"*
-------------------------

* Not an abstract class.
* Provides a "base" implementation of an interface or an abstract class.
* The class can be instantiated and not used any more, but is designed for the user of the extended component.
  
* Do not use this prefix if no interface or parent abstract class exists.

Example::

   public abstract class StreamRequestHandler {}
   public class BaseHTTPRequestHandler extends StreamRequestHandler {}
    

Using the suffix *"Impl"*
-------------------------

* It is a class instance and therefore can't be abstract
* It is a complete implementation of an interface or abstract class, generally referred to as the class without the "impl". 
  
* Other classes should not be extended from it.
* Do not use this suffix unless the class name conflicts with the name of the interface or abstract class being implemented. 
  
* If this is the default implementation of part of the API and does not conflict with other parts of the project, the prefix *Default* is preferred. 
  

Example::

   public interface Plane {}
   public abstract class AbstractPlane implements Plane {}
    
   // Both are correct (but not equal)
   public class PlaneImpl implements Plane {} 
   public class PlaneImpl extends AbstractPlane {}


Application Conditions
======================

This criterion is applicable to new developments undertaken for gvSIG 2.0 and will be part of the official gvSIG distribution as well as for all developments financed in whole or in part by the CIT.