Software Development Guidelines

Software development conventions are important in a multi-developer project, and help developers read and understand each other's code. Please try to follow our five major guidelines in spirit. Your cooperation will improve the effectiveness of the collaboration.

1. Try not to hinder other developers
• make sure code compiles before committing it
• make sure code passes all tests (if they exist) before committing
• if you need to check in broken or incomplete code, use a branch, or somehow minimize the impact on other developers
2. Commit code that is neat, portable, and documented
• indent using spaces instead of tabs, usually 4 spaces but 2 is ok too, just be consistent
• use braces consistently (cuddled or not) within a file
• use braces for all if-statements, including one-line conditionals
• use 80-character lines max (this is very important for code)
• use appropriate, descriptive names for classes and variables
• camel caps for variable names, starting with lower case (e.g., myVariable)
• camel caps for class names, starting with upper case (e.g., MyClass)
• use javadoc or equivalent comments for every class and method
• explain the purpose and intent of a class and how it fits into the overall architecture when writing docs
• remove extraneous code that is not used (classes, and methods in classes)
3. Communicate with other developers
• commit frequently, in small and logically related patches with good log messages
• use a transparent build system to expose all dependencies and requirements to build a project. We like Ant, but other build tools are possible too.
4. Try not to check in files (JARs and generated documentation like javadocs) that can be generated from the build system. This wastes space and slows down checkouts.
5. Try not to check in code that uses System.out or System.err to print messages to the console. There is already an easy-to-use logging framework in Kepler - see the Quick Start Guide to Logging in Kepler

In addition, try to follow the Java programming guidelines in general.

We also recommend that people write short, to-the-point methods that encapsulate a very specific behavior, rather than long procedural functions. If your methods are longer that 30-40 lines of code, or if they have extensive conditional blocks or switch statements, they might be broken up into several methods. But this is very subjective. Related to this is the importance of factoring out common procedures into their own classes or methods; if you find yourself writing the same type of functionality multiple times, it's definitely time to refactor.

We do not yet fully meet these ideals in our own work, although we should always push for it whenever we find problems.