From 69c5c0e07f834c83ec4e8f6f90df321d0702fa4f Mon Sep 17 00:00:00 2001 From: Michael Smith Date: Sat, 29 Jun 2002 03:49:01 +0000 Subject: [PATCH] Formalize naming conventions proposal. Submitted by: Stephen Colebourne I made a few minor modifications (e.g. adding tags), along with modifying the requirement of static inner classes for the decorators to be more in line with my perception of consensus from the discussion. git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@130737 13f79535-47bb-0310-9956-ffa450edef68 --- DEVELOPERS-GUIDE.html | 94 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 DEVELOPERS-GUIDE.html diff --git a/DEVELOPERS-GUIDE.html b/DEVELOPERS-GUIDE.html new file mode 100644 index 000000000..a4897bb28 --- /dev/null +++ b/DEVELOPERS-GUIDE.html @@ -0,0 +1,94 @@ + + +Developers guide for Jakarta Commons "Collections" Package + + + + +
+

The Jakarta Commons Collections Package

+

Developers Guide

+$Id: DEVELOPERS-GUIDE.html,v 1.1 2002/06/29 03:49:01 mas Exp $
+[Introduction] +[Collection Interfaces] +[Collection Implementations] +[Utility Classes] +

+
+ + + +

1. INTRODUCTION

+ +

The Collections package contains a set of Java classes that extend +or augment the Java Collections Framework. This developers guide seeks to set +out rules for the naming of classes and methods within the package. The purpose +of this, as with all naming standards, is to improve the coherency and +consistency of the whole API.

+ +

The philosophy of the naming standards is to follow those of +java.util.Collections.

+ + + +

2. COLLECTION INTERFACES

+ +

Collection interfaces are new types of collections not included in Java. +Examples include Bag and SortedBag. These interfaces +shall:

+ + + + +

3. COLLECTION IMPLEMENTATIONS

+ +

Collection implementation are new implementations of collection interfaces. +Examples include DoubleOrderedMap and DefaultMapBag. +These interfaces shall:

+ + + + +

4. UTILITY CLASSES

+ +

Utility classes provide additional functionality around an interface and +its basic implementations. Examples include CollectionUtils and ListUtils.

+ +

Each class shall follow the naming pattern XxxUtils where Xxx relates to the +object being returned by the class, for example ListUtils and +BagUtils. Variations on a theme (SortedBag as opposed +to Bag) will be dealt with in one Utils class. Each Utils class +shall:

+ + + +

Where the method in a Utils class is a decorator, the naming pattern +yyyedXxx shall be used, such as synchronizedMap(Map) or +predicatedSet(Set). Typically, these decorators should be +implemented as non-public, static, inner classes; however, if warranted due to +maintenance or other reasons, these decorator classes may be moved to top-level +classes in a subpackage. The naming of such a subpackage should be discussed +and agreed upon on the developers mailing list.

+ + + + +