| 1 |
<!-- |
| 2 |
Licensed to the Apache Software Foundation (ASF) under one or more |
| 3 |
contributor license agreements. See the NOTICE file distributed with |
| 4 |
this work for additional information regarding copyright ownership. |
| 5 |
The ASF licenses this file to You under the Apache License, Version 2.0 |
| 6 |
(the "License"); you may not use this file except in compliance with |
| 7 |
the License. You may obtain a copy of the License at |
| 8 |
|
| 9 |
http://www.apache.org/licenses/LICENSE-2.0 |
| 10 |
|
| 11 |
Unless required by applicable law or agreed to in writing, software |
| 12 |
distributed under the License is distributed on an "AS IS" BASIS, |
| 13 |
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 14 |
See the License for the specific language governing permissions and |
| 15 |
limitations under the License. |
| 16 |
--> |
| 17 |
<html> |
| 18 |
<head> |
| 19 |
<title>Developers guide for Apache Commons "Collections" Package</title> |
| 20 |
</head> |
| 21 |
<body bgcolor="white"> |
| 22 |
|
| 23 |
|
| 24 |
<div align="center"> |
| 25 |
<h1>The Apache Commons <em>Collections</em> Package</h1> |
| 26 |
<h2>Developers Guide</h2> |
| 27 |
$Id: DEVELOPERS-GUIDE.html 646782 2008-04-10 12:58:57Z niallp $<br /> |
| 28 |
<a href="#Introduction">[Introduction]</a> |
| 29 |
<a href="#CollectionInterfaces">[Collection Interfaces]</a> |
| 30 |
<a href="#CollectionImplementations">[Collection Implementations]</a> |
| 31 |
<a href="#UtilityClasses">[Utility Classes]</a> |
| 32 |
<a href="#CodingStandards">[Coding Standards]</a> |
| 33 |
<br /> |
| 34 |
<br /> |
| 35 |
</div> |
| 36 |
|
| 37 |
|
| 38 |
<a name="Introduction"></a> |
| 39 |
<h3>1. INTRODUCTION</h3> |
| 40 |
|
| 41 |
<p>The <em>Collections</em> package contains a set of Java classes that extend |
| 42 |
or augment the Java Collections Framework. This developers guide seeks to set |
| 43 |
out rules for the naming of classes and methods within the package. The purpose |
| 44 |
of this, as with all naming standards, is to improve the coherency and |
| 45 |
consistency of the whole API.</p> |
| 46 |
|
| 47 |
<p>The philosophy of the naming standards is to follow those of |
| 48 |
java.util.Collections.</p> |
| 49 |
|
| 50 |
|
| 51 |
<a name="CollectionInterfaces"></a> |
| 52 |
<h3>2. COLLECTION INTERFACES</h3> |
| 53 |
|
| 54 |
<p>Collection interfaces are new types of collections not included in Java. |
| 55 |
Examples include <code>Bag</code> and <code>SortedBag</code>. These interfaces |
| 56 |
shall:</p> |
| 57 |
<ul> |
| 58 |
<li>be top level interfaces</li> |
| 59 |
<li>have a name that describes their purpose</li> |
| 60 |
</ul> |
| 61 |
|
| 62 |
|
| 63 |
<a name="CollectionImplementations"></a> |
| 64 |
<h3>3. COLLECTION IMPLEMENTATIONS</h3> |
| 65 |
|
| 66 |
<p>Collection implementation are new implementations of collection interfaces. |
| 67 |
Examples include <code>DoubleOrderedMap</code> and <code>DefaultMapBag</code>. |
| 68 |
These interfaces shall:</p> |
| 69 |
<ul> |
| 70 |
<li>be top level classes</li> |
| 71 |
<li>have a name that ends with the collection type being implemented</li> |
| 72 |
<li>have a name that describes their implementation</li> |
| 73 |
<li>contain no public inner classes</li> |
| 74 |
<li>only contain the collection implementation, and any methods specific to |
| 75 |
that implementation</li> |
| 76 |
</ul> |
| 77 |
|
| 78 |
|
| 79 |
<a name="UtilityClasses"></a> |
| 80 |
<h3>4. UTILITY CLASSES</h3> |
| 81 |
|
| 82 |
<p>Utility classes provide additional functionality around an interface and |
| 83 |
its basic implementations. Examples include CollectionUtils and ListUtils.</p> |
| 84 |
|
| 85 |
<p>Each class shall follow the naming pattern XxxUtils where Xxx relates to the |
| 86 |
object being returned by the class, for example <code>ListUtils</code> and |
| 87 |
<code>BagUtils</code>. Variations on a theme (<code>SortedBag</code> as opposed |
| 88 |
to <code>Bag</code>) will be dealt with in one Utils class. Each Utils class |
| 89 |
shall:</p> |
| 90 |
|
| 91 |
<ul> |
| 92 |
<li>be a single, static method based, class</li> |
| 93 |
<li>have a name consisting of the interface name plus 'Utils'</li> |
| 94 |
<li>deal with one collection interface and its variations</li> |
| 95 |
<li>provide methods that decorate the interface with additional |
| 96 |
functionality</li> |
| 97 |
<li>provide methods that perform useful utility functions on that |
| 98 |
interface</li> |
| 99 |
</ul> |
| 100 |
|
| 101 |
<p>Where the method in a Utils class is a decorator, the name shall consist of |
| 102 |
an adjective followed by the collection type. Typically such adjective is |
| 103 |
formed by appending an -ed suffix (meaning "having"/"characterized by") to the |
| 104 |
word describing the type of decorator. For example, |
| 105 |
<code>synchronizedMap(Map)</code> or <code>predicatedSet(Set)</code>. |
| 106 |
Occasionally, such construct is awkward and a more suitable adjective can be |
| 107 |
used instead. For example, <code>lazyList</code>, |
| 108 |
<code>unmodifiableList</code>.</p> |
| 109 |
|
| 110 |
<p>These decorators should be implemented either as non-public, static, |
| 111 |
inner classes, or as public classes in a subpackage. If a subpackage is used, |
| 112 |
the constructors should be protected and a public static decorate() method |
| 113 |
provided on each class for construction.</p> |
| 114 |
|
| 115 |
<a name="CodingStandards"></a> |
| 116 |
<h3>5. CODING STANDARDS</h3> |
| 117 |
|
| 118 |
<p>Commons Collections follows similar style rules to many other Java open source |
| 119 |
projects, and the Sun conventions. Some specific conventions are:</p> |
| 120 |
|
| 121 |
<ul> |
| 122 |
<li>No tabs, 4 space indentations</li> |
| 123 |
<li>Curly brackets open at line end</li> |
| 124 |
<li>Else, catch and finally statements after the closing bracket</li> |
| 125 |
<li>Single space after keyword such as if</li> |
| 126 |
<li>Two spaces between parameter name and description in @param</li> |
| 127 |
<li>Generally copy the style of the surounding code</li> |
| 128 |
</ul> |
| 129 |
|
| 130 |
<p>And rememeber, the commons-dev mailing list is there for any discussions |
| 131 |
or queries about patches or new additions to collections.</p> |
| 132 |
|
| 133 |
</body> |
| 134 |
</html> |