[JGAP Home]
The following is a short list of guidelines to follow when contributing code or patches to the JGAP project. Before we commit any code to the CVS repository, we need to make it follow these guidelines (for protection of our own sanity), so it's a lot easier on us if your code simply adheres to the guidelines when you submit it :-) Thanks!
A sort of ironic compilation of dont do's can be found in Roedy Green's article, it's worth a read.
All new code files must have a copyright statement at the top that reads:
/* * This file is part of JGAP. * * JGAP offers a dual license model containing the LGPL as well as the MPL. * * For licensing information please see the file license.txt included with JGAP * or have a look at the top of class org.jgap.Chromosome which representatively * includes the JGAP license policy applicable for any file delivered with JGAP. */
When importing classes with the import statement, use the generic form and don't import single classes:
import java.util.*; // correct
import java.util.List; // WRONG
Do not format javadocs by adding unnecessary spaces or indentation (javadoc output will do this!)
Do not start a javadoc for parameters with a capital letter. Do not end such text with a period.
In methods: Order of javadoc elements should be:
description of method
add a blank line
parameters (if existent)
return value (if not void)
throws (if existent)
add a blank line
author
since (here you should enter the next JGAP version to be released, i.e. "2.4" (without quotation marks)).
All classes, methods, and fields require javadocs, including private methods and fields and the main method.
All in-line comments should be "underlined." For example:
// This is an in-line comment. // Notice that it is underlined. // ----------------------------- doSomeWork();
Indent 4 spaces. No tabs, please.
Lines of code should not exceed 79 characters in length. Please take this very seriously!
Curly braces go on the same line, no extra indentation. For example:
public void foo() {
doSomeWork();
}
Always but the statements after an if or else-statement in curly braces, like:
if (condition) { // this curly brace is required
statement1;
statement2;
}
Class names always start with a capital letter and contain no underscores. THIS IS VERY IMPORTANT!
Class and instance variables, other than constants, should start with m_. For example:
private int m_myField;
Method arguments should always begin with "a_". For example,
public void foo(int a_someValue);
Constants should be in all capitals. For example,
public static final int MY_CONSTANT_VALUE = 1;
In interfaces, don't use the key word public for declared methods.
Favor clean, readable, maintainable code over optimized code. Let a profiler determine where the bottlenecks exist and then optimize as little as possible to achieve desired performance. When you do optimize, please leave a very detailed comment explaining that the code has been optimized and what it is doing.
Currently, we are not using Java 1.4 assertions in the JGAP code. We may begin doing so in the future, but for now please leave them out.
If you end up creating a new package, please also create a package.html file that explains the purpose of that package. Javadoc will use this file to generate a package description.
In general, favor descriptive method and variable names over in-line comments. For example, instead of:
// Calculate area of circle // ------------------------ x = 2 * PI * r * r;
Do:
areaOfCircle = getAreaOfCircle( circleRadius );
When adding a new class or new method, you could add the RFE number in the javadoc comment.
For each new class introduced there should be one new (JUnit) test class created extending junit.framework.TestCase (see the JGAP unit tests for examples)
Each test case class is added to a test suite class containing a reference to all unit tests in the package the test suite class is lying. See org.jgap.impl.AllImplTests for example.
Test clase and test suite classes are lying in a different directory branch than the source code classes. Please see the JGAP CVS: src is the toplevel directory for source code and test is the toplevel directory for test code. Please notice, that the src and test directory both have the same package hierarchy!
For test cases, the class heading javadoc should write (e.g. for class StringGene):
/* * Tests the StringGene class * ... * @author ... * @since <JGAP version the test was first introduced in, e.g: @since 3.6, see main page for current version or ask the admin> */
Don't add any outputs to the console (System.out or System.err) in your test cases. In nearly any case this could be avoided completely by using explanatory messages with exceptions or the JUnit fail(...) method.
It might be useful looking at the existing unit tests to get some hints about how to do exception handling etc. Also see Test-Driven Development: Useful Techniques, Resources.
The blog entry Intentionally failing JUnit tests could be a useful resource.
If you don't feel sure when to write your tests (before, during or after coding), the blog entry When TDD is not optimal might be useful.
For developers, it's ok to commit in-progress code to CVS that doesn't work, but please try to avoid committing code that doesn't compile or that completely breaks everything. If you're going to be doing a lot of work that will likely break everything, we can consider creating a branch for you to work on until your code is at least semi-stable.
It is better to check in quite often than to wait too long with committing your work.
When checking in something to the CVS, you should do this per class as you could then add a useful comment. It is not forbidden adding the RFE number (the request number from the JGAP sourceforge RFE page) in the comment!
If using WinDiff: It's much more comfortable using an external viewer (such as WinMerge) than using the internal textual representation.
Finally, you may find JGAP code that doesn't adhere to one of the rules. That doesn't mean it's ok to disregard them in your code! ;-)
If you think an important functionality is missing or there is a design flaw in JGAP, feel free to post this as a RFE or drop a short note to the JGAP admin (see main page).
Copyright © 2002-2012 Klaus Meffert / Neil Rotstan. All rights reserved.
[JGAP Home]