Development Conventions

Coding Style

A consistent coding style makes development much easier and the code much more readable. Because of that the Jummp development follows a very strict coding style. There are many existing code style guidelines and it does not make sense to add yet another one, therefore we just point to an existing one and add our additions.

Jummp follows the Java Coding Style as described by geosoft with the following corrections and additions:

• (8) "Private class variables should have underscore suffix": this rule can be relax, as if we follow the encapsulation paradigm, most of the variables would have this "_" in their name... Cf. rule (46): "Class variables should never be declared public".
• (9) "Generic variables should have the same name as their type": this rule can be relaxed in some cases (when it makes the method clearer)
• (34) "File content must be kept within 100 columns"
• (61) Indentation are 4 whitespaces, no tabs. Rationale: whitespaces are easier to read when using a terminal for viewing code diffs as it happens with Mercurial.
• (61) Braces should be used after each if/for/while statement. It is:

  if (foo)  
  {  
      bar()  
  }
  

  and not

  if (foo)  
      bar()
  

Rationale: if in future it is required to extend the code block formatting changes have to be added to a changeset. This is undesired. Furthermore it is easy to get the if statement wrong if it is not in a block. * (74) "Method names can be followed by a white space when it is followed by another name": no white space after a method's name. * (74) "Methods should be separated by three blank lines": 2 blank lines is sufficient. * Newline at end of file is required. Rationale: that makes version control systems happy. * Line breaks in Unix style. Rationale: most development tools like hg diff are Unix centric. Windows line break results in ugly markers. * Preferred indentation style K&R style: this mainly means that the braces should be alone on the line. Rationale: this greatly increases code readability.

Groovy Additions

Jummp uses the Grails framework which uses Groovy. Groovy is a dynamic programming language inspired by Java and compiled into Java Bytecode. It adds useful additions to the language, but some additions are not helpful at all and make it harder to read the code. Therefore the following Groovy coding style conventions are defined:

• Use return statement. Rationale: Groovy interprets the last statement implicitly as a return statement. This makes the code difficult to read in case of if/else constructs returning different values.
• Specify return type of methods. Rationale: Groovy won't complain if there is a type mismatch, but the application won't work. Such errors are hard to track and tend to be Bohrbugs. Make life of all developers easier by saying what you return. Other developers should be able to use your method without having to read the code.
• Specify visibility of methods. Rationale: With Grails dependency injection you can easily just ignore visibility of your service methods. Nevertheless mark your private methods. That way other developers can see that the method is not intended to be used outside the class.
• Use generics where feasible. Rationale: Groovy lists and maps allow to mix any kind of objects. While this is fast to program it's a step backwards to the time before Java 5. If you know that your List is specific to one type, specify it. You won't get compile errors but good IDEs are able to outline possible problems if you add other types to the list.
• Don't use def if you know the type. Rationale: when specifying the type the IDE can help you with auto complete features. Typing everything yourself is dangerous. Remember: groovy won't complain about typos, those are runtime errors.
• Use parentheses (surrounding the parameters) when invoking methods and closures: this increases readability of the code.
• Remove all trailing whitespaces.

IDE Configuration

IntelliJ IDEA code style configuration file: AVAILABLE SOON.

Download the XML file and copy it to ~/.IntelliJIDEA/config/codestyles then restart IDEA. On Windows, try C:\Documents and Settings<username>.IntelliJIDEA\config\codestyles. After this, restart IDEA and open the settings to select the new code style.

Testing

All service methods must have a unit test for their contract. A new method may not be pushed if the unit test has not been written yet. Before pushing new changes it has to be ensured that all unit tests are still functional and changes breaking the unit tests are not allowed to be pushed.

Commit procedure

It is good practice to only commit a set of changes relative to one single action (bug fix, new feature, ...) and not commit various changesets at once.

How Development happens

Development does not happen directly in the Jummp repository. Each developer has to have a clone where he should work on new features and bug fixes. Before a change is merged into the Jummp repository the developer has to do a pull request. The Development Team has to review the changes and push it to the repository. A developer with push access to the Jummp repository is not allowed to push his changes directly. It has to be pushed by another developer with push access to ensure that only reviewed code is committed into the repository. A change may only be pushed if at least one other developer has reviewed the code.

Documentation

All public API has to be documented properly, for private parts it is recommended to add documentation. For generating the API documentation Doxygen is used. Doxygen is compatible with JavaDoc, but adds many useful additional tags and generates a better browsable HTML documentation and optionally also LaTeX sources. The additions from Doxygen are ignored when using JavaDoc, so it is still possible to use JavaDoc to generate the documentation.