Contents

Coding Conventions

General

Sun has established coding standards that are generally considered reasonable, as evidenced by their widespread adoption by other Java-based development efforts (e.g., the Apache Jakarta project). One of the goals is to make the Janus projects blend in with the Java 2 platform. This goal is furthered by our following suit.


Sun's Code Conventions for the Java Programming Language covers filenames, file organization, indentation, comments, declarations, statements, white space, naming conventions, and programming practices. All code written for the Janus projects should follow these conventions except as noted below. We deviate only in places where our needs differ from Sun's; when we do deviate, we explain why. (The section numbers shown below are Sun's.)

Additional Guidelines

In the following additional guidelines, the keywords between braces and prefixed with a dollar sign, eg. ${year}, are corresponding to the Eclipse macro of the name names.

Section 3.1.1 Beginning Comments

The Janus project has specific guidelines for copyright notices to appear at the beginning of source files. Each file must start with one of the following comments, depending on the copyright of the source code.

Standard Janus Project Header (GPL v3 License)

/* 
 * $Id$
 * 
 * Janus platform is an open-source multiagent platform.
 * More details on <http://www.janus-project.org>
 * Copyright (C) ${year} Janus Core Developers
 * 
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 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 General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

Standard SeT Laboratory Header (Proprietary License)

/* 
 * $Id$
 * 
 * Copyright (c) ${year}, Multiagent Team,
 * Laboratoire Systemes et Transports,
 * Universite de Technologie de Belfort-Montbeliard.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information
 * of the Laboratoire Systemes et Transports (SET)
 * of Universite de Technologie de Belfort-Montbeliard.
 * You shall not disclose such Confidential Information and shall use
 * it only in accordance with the terms of the license agreement
 * you entered into with the SET.
 *
 * http://www.multiagent.fr/
 */

Standard CITAT Laboratory Header (Proprietary License)

/* 
 * $Id$
 * 
 * Copyright (c) ${year}, Centro de Investigaciones de Tecnologías Avanzadas de Tucumán,
 * Facultad Regional de Tucumán, Universidad Tecnológica Nacional.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information
 * of the Centro de Investigaciones de Tecnologías Avanzadas de Tucumán
 * (CITAT) of Universidad Tecnológica Nacional.
 * You shall not disclose such Confidential Information and shall use
 * it only in accordance with the terms of the license agreement
 * you entered into with the CITAT.
 *
 * http://www.frt.utn.edu.ar/citat/cms/index.php?lang=english
 */

Section 5.2 Documentation Comments

The Janus project has specific guidelines for package, class and interface comments. Each package, class and interface must start the following comment template:

/**
 * ${todo}
 * @author $$Author: ${user}$$
 * @version $$Name$$ $$Revision$$ $$Date$$
 * @mavengroupid $$GroupId$$
 * @mavenartifactid $$ArtifactId$$
 * ${tags}
 */

The macros enclosed by dollar signs are supported and automatically replaced by the maven plugin [org.arakhne.afc:maven-javadoc-tag-replacer] when generating the API documentation.

Macro Replacement
$Author: n$ Put the name of the developer with the identifier or email equal to n in the Maven pom.xml file. Or put the name of the contributor with the email equal to n in pom.xml.
$Name$ Put the name of the maven module reteived from the pom.xml file.
$Revision$ Put the version number of the maven module reteived from the pom.xml file.
$Version$ Put the version number of the maven module reteived from the pom.xml file.
$Date$ Put the release date of the maven module reteived from the pom.xml file.
$GroupId$ Put the group id of the maven module reteived from the pom.xml file.
$ArtifactId$ Put the artifact id of the maven module reteived from the pom.xml file.

For example the class fr.utbm.set.gis.util.GISTreeSet:

/**
 * This class describes a quad tree that contains GIS primitives
 * and that permits to find them according to there geo-location.
 * 
 * @param <P> is the type of the user data inside the node.
 * @author $Author: sgalland$
 * @version $Name$ $Revision$ $Date$
 * @mavengroupid $GroupId$
 * @mavenartifactid $ArtifactId$
 * @see GISPrimitive
 */
public class GISTreeSet<P extends GISPrimitive> implements Set<P> {


Section 7.9 Try-Catch Statements

When catching all throwable objects and not forwarding any exception form the catching code, insertion of a catch statement on assertion failures prior to catch-all statement is encouraged.

try {
   // Code
}
catch(AssertionError e} {
   throw e; // Forward all assertions
}
catch(Throwable e} {
   // Code which is not throwing e
}

Section 9 Naming Conventions

The Janus project has more specific naming conventions. See Project Naming Conventions for details.

Additional Conventions about Property files

  • Property files (.properties extension) are text files with Java resource descriptions. The following notice must appear at the beginning of each property file:
# $Id$
#
# Copyright (c) %%year%%, %%developers%%
# All rights reserved.
#
# http://www.janus-project.org


New Section 10.5.5 No standard or error outputs

The standard and error streams should be remove from the source code. A logger should be used in place.

System.out.println("out message"); // WRONG
System.err.println("err message"); // WRONG
 
Logger logger;
logger.info("out message"); // RIGHT
logger.error("err message"); // RIGHT

The same rule should be applied to the stack trace output of the exceptions.

Throwable t;
t.printStackTrace(); // WRONG
 
Logger logger;
logger.error(Throwables.toString(t)); // RIGHT

Note that Throwables is an utility class provided by the Janus maven module org.janus-project.kernel:util.

New Section 10.5.6 No Thread Creation Outside an Executor

A thread must no more be created by directly instance the Thread class. The executor API must be used in place.

Runnable r;
 
new Thread(); // WRONG
new Thread(r); // WRONG
 
ExecutorService executors = Executors.newCachedThreadPool(); // RIGHT
executors.submit(r); // RIGHT

Eclipse Configuration

Your Eclipse Platform should be configured as following: (section "Preferences> Java> Compiler> Error/Warnings"): every options must be set to "Warning", except for those in Table 1.

Configuration Option Value
"Code Style> Parameter assignement" Ignore
"Potential programming problems> Boxing and unboxing conversions" Ignore
"Deprecated and restricted API> Deprecated API" Error
"Deprecated and restricted API> Forbidden reference" Error
"Unnecessary code> Parameter is never read" Ignore

To quickly configure your Eclipse IDE, you may import one of the following preferences:

Eclipse Version Janus Headers IRTES-SET Headers CITAT Headers
Galileo zipped-epf zipped-epf
Indigo zipped-epf zipped-epf
Juno zipped-epf zipped-epf
Kepler zipped-epf zipped-epf

Related Pages

2016-01-24SARL 0.3.1 and Janus 2.0.3.1 are available.
2015-11-30SARL 0.3.0 and Janus 2.0.3.0 are available.
This page was last modified on 2 July 2013, at 12:06. This page has been accessed 10,085 times.
Copyright 2010-2017 © Janus Core Developers - Privacy policy