News Operations
Browse SpaceCoding conventions describe the coding styles developers should use when writing code. For example, whether you use 2, 4, or 8 space indents. Standardizing on a coding style across a project improves legibility of the code, and automatic code formatters make conforming to these standards easy.
Sun Coding Conventions and a little bit more
We follow:
- Sun's coding convention: http://java.sun.com/docs/codeconv/
- but allow for 100 characters in width
- developers should use spaces for indentations, not tabulations
(because the tab width (4 or 8 spaces) is not the same on all editors)
To help make this easy we have chosen to use Jalopy.
Jalopy
| Jalopy | http://jalopy.sourceforge.net/ |
|---|
Jalopy is a source code formatter for Java. It lays out any valid Java source code according to configurable rules to meet a coding style without putting a formatting burden on individual developers.
Geotools has defined a set of conventions, based on the Sun's coding standards, that each developer should try to respect. The full definition is contained in the build-configs module.
Jalopy is integrated in the maven build system, and can be used interactively or enabled as part of the normal build.
If you want to run it interactively on the current module, just use:
mvn jalopy:format
Module mantainers can also decide to enable Jalopy permanently as part of the maven build adding the following declarations to the module pom.xml file:
<!-- ==================================================== --> <!-- Enable jalopy reformat --> <!-- ==================================================== --> <build> <plugins> <plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>jalopy-maven-plugin</artifactId> <executions> <execution> <goals> <goal>format</goal> </goals> </execution> </executions> </plugin> </plugins> </build>
As an alternative, Jalopy can be integrated into a number of IDEs, and a project's coding convensions can be stored centrally and imported by all developers. Installation is straight forward, refer to the Jalopy documentation for details, and remember to import the geotools conventions.
What this Means for You?
It means that we are not going to weight down this document with a description of everything that must be done when working on the geotools codebase. The tool will fix it all - please use the tool.
But what about the header?
The header for all core GeoTools code is:
/* * GeoTools - The Open Source Java GIS Toolkit * http://geotools.org * * (C) 2004-2008, Open Source Geospatial Foundation (OSGeo) * * This library 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; * version 2.1 of the License. * * This library 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. */
The header for all demo code is:
/* * GeoTools - The Open Source Java GIS Toolkit * http://geotools.org * * (C) 2004-2008, Open Source Geospatial Foundation (OSGeo) * * This file is hereby placed into the Public Domain. This means anyone is * free to do whatever they wish with this file. Use it well and enjoy! */
But really Jalopy could take care of this for you - please use the tool.
For my self, I would suggest to be careful with Jalopy uses. It may be useful for fixing a badly formatted file. But from that point, human formatting do a better job than Jalopy can do. It is common to format a code like a table. For example related parameter can be put together:
double someFunction(double x1, double y1, double x2, double y2, double x3, double y3);Complex formulas are often formatted in an human-understandable way too (putting spaces between some terms because they have a meaning of special interest, etc.). Successive "if" statements can be formatted as a table too. Example:
if (op != null) { if (op.i.path==path) fermions.put(op.i, op); if (op.j.path==path) fermions.put(op.j, op); } if (np != null) { if (np.i.path==path) fermions.put(np.i, np); if (np.j.path==path) fermions.put(np.j, np); }Jaloppy would put the 'fermions.put' calls on the next line, which make the code harder to read because it breaks the tabular format. It is also more bug prone because the symmetry would become less apparent (I tend to believe that a well designed code often have symmetry in it, and making the symmetry more apparent help to check for errors).
etc. Special formatting just around in about every corners of the code. At the very least, do NOT run Jaloppy on my code. It badly break the formatting, it doesn't improve it at all. To be honest, I really dislike any automatic-formatting tools.