Work at SourceForge, help us to make it a better place! We have an immediate need for a Support Technician in our San Francisco or Denver office.

Close

[r11492]: cdk-policy / trunk / code.tex Maximize Restore History

Download this file

code.tex    81 lines (64 with data), 3.1 kB

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
\section{Code Requirements}
This section formalized the concept of stable code. This stableness involves code quality, unit
tests, etc, all to increase the portability and maintainability of the CDK library. This section
of the policy applies to \trunk of the CDK library (MUST), but developers are encouraged to apply
it to other branches too (SHOULD).
\subsection{Non-Source Files}
Files other than source files can be divided into two groups: test files, and
data files used upon runtime of the library. The former should go into
\emph{src/data} while the runtime data files must go into the
\emph{src/main/org/openscience/cdk} tree.
For example, the templates for the structure diagram generator, such as a
template for cubane is stored in
\emph{src/main/org/openscience/cdk/layout/templates}.
\subsection{Source Files}
\subsubsection{Header}
The header of a CDK source file must look like:
{\small
\begin{verbatim}
/* $Revision: 11464 $ $Author: egonw $ $Date: 2008-06-30 15:36:34 +0200 $
*
* Copyright (C) 1997-2003 Some User <some.user@example.org>
* 2003-2007 Other User <other.user@example.org>
*
* Contact: cdk-devel@lists.sourceforge.net
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public License
* as published by the Free Software Foundation; either version 2.1
* of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*/
\end{verbatim}
}
The copyrights lines are important, and indicate who wrote the source code.
It is important that this is filled out properly, as it is used to contact the
original authors in case of legal issues. The lines:
{\small
\begin{verbatim}
* Copyright (C) 1997-2003 Some User <some.user@example.org>
* 2003-2007 Other User <other.user@example.org>
\end{verbatim}
}
indicate that \emph{Some User} worked on the code in the period 1997--2003,
while \emph{Other User} worked on it from 2003 to 2007. The email address must
be included.
\subsection{Unit Tests}
All code entering \trunk must be covered by unit tests. All public and protected methods
must be called in at least one unit test \@Test method.
\subsection{PMD Error Free}
All code entering \trunk must not trigger PMD warnings of level FIXME...
The rule sets used follow the PMD releases, with the exception of a number of rules tuned for
the \CDK which should be considered integral part of this policy, and for which the source
can be found in an appendix of this policy.
\subsection{JavaDoc}
All code entering \trunk must have full JavaDoc for the classes, public and protected methods
and/or fields.