Getting started

We suggest the following approach for everybody who wants to contribute code to Bloof:

  1. Checkout the latest version from the bloof cvs repository .
  2. Download MAVEN from MAVEN web site , following the instructions there.
  3. Run maven in the directory where you extracted Bloof. This can take some time. MAVEN will download some of the dependencies that are required by Bloof.
  4. Download the remaining jar files from dependencies page and copy them by hand into the appropriate MAVEN repository directory.
  5. Run maven eclipse . This will generate an ECLIPSE project file.
  6. Get ECLIPSE from www.eclipse.org . Use it for any further activity on the Bloof project.

Coding Styles

In the following I will shortly explain the basic coding standards used in my code. Any developer who wants to contribute is encouraged to follow those. My main interest is in the documentation of all changed or added methods and variables etc. There?s nothing worse than guessing what code changes are meant to do. The documentation standards are pretty obvious actually if you look at the code. But to make things easier I will explain them nonetheless.

1.1 Class Style

Every class contains the GPL notice at the beginning for obvious reasons. This comment also contains the class? filename and its creation date in the last lines. Every developer is strongly encouraged to add a changed date together with a short description of the committed changes there. Additionally, I always use the javadoc class documentation to create a short description of the things a class is there for. This documentation also contains an @author field where any other developer should just add his or her name: 

      
/**
 * This class manages the externalization of strings that 
 * will possibly be presented to the user
 * @author Lukasz Pekacki <pekacki@users.sourceforge.net>
 * @version $Id: developer-guide.xml,v 1.4 2003/10/13 15:52:36 pekacki Exp $
 */
public class Messages {

I always try to sort class methods in a way, that makes the class generally more readable. That usually means that public methods are written first, followed by the protected and the private ones in that order. Variables are only and exclusively defined in the beginning of a class and import statements are in most cases written using the fully qualified domain name instead of using package imports.

1.2 Method Style

Every method has a javadoc comment as complete as possible. This means especially to use the @param and @return fields evaluated by the javadoc tool to document the parameters and the return values. If necessary, use @throws to document the Exceptions which can be thrown and more importantly the conditions in which they are thrown. If a method is not an interface method with an obvious meaning also document where this method is used to make it easier to understand code patches. You will find multiple examples in my code where I also did that. With all that polymorphism and other object-oriented it?s not always easy to see. If you developed some longer more complicated algorithm, which is something not always avoidable in graphics programming, also document what your algorithm does using one line comments. 

      /**
* Returns the value for the specified key. key-value pairs 
* are specivied
* in the resourcebundle properties file.
* @param aKey
* @return String
*/
public static String getString(String 
  aKey) {

1.3 Naming Convetions

Artifact Naming Pattern Example
constant ^[A-Z]([A-Z0-9_]*[A-Z0-9])?$ BLAH
static member ^s[a-z][a-zA-Z0-9]*$ sBlah
class member ^m[A-Z][a-zA-Z0-9]*$ mBlah
method attribute ^a[A-Z][a-zA-Z0-9]*$ aBlah
local variable ^[a-z][a-zA-Z0-9]*$ blah

1.4 Golden Code Conventions

  • No magic numbers; exception: 0,1 allowed in loop statements or if statements
  • No magic strings; every string that will potentially be presented to the user is to be fetched from the message bundle
  • Keep your classes small and tidy
  • Handle every exception, at least with a stack trace
  • No System.out or System.err statements; use logger instead