Debian Codegraph @

DEVELOPERS-GUIDE.html

raw
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>