Coding Conventions

Coding conventions are a preferred way of doing things.

Files

• Although Grails can handle both dos (\r\n) and *nix (\n) line ends only (\n) should be used, please configure your IDE or editor.
• It is project policy not to include developer's names in the source files, recognition will be given in better and more visible ways.

Format

• Please configure your IDE or editor to use an indent of 4 spaces, with no tabs.
• Follow the generally used formatting of code you see in Grails and this project.

Grails

• As much as possible try to keep the CRUD pages as generated by "grails generate-all"
• For example the Task views and controller are retained as is for application administration.
• If we want to modify the Task views and controller:
  • Create a copy of the whole views folder called TaskDetailed/show.gsp etc
  • Create a copy of the controller called TaskDetailedController.groovy and edit the class inside to match.
  • Then detail to your hearts content.

This way the original views are available as direct access to the data for administration. If the domain changes a "grails generate-all" can be performed on most domains without losing the customisations.

The 'Detailed suffix was chosen as in detailing a car, customised or air-brushed.

A notable exception to this is Person and Authority use 'svn revert' if you accidentally regenerate these.

Documentation

Use self documenting code:

• A few extra lines of clear, commented and readable code has more value than 100 lines of API documentation explaining why the code is so complicated.
• Coders are better off reading code and no-one else reads API documentation.
• Don't abbreviate: LinIntDist could mean a wide range of things, LinthianInternalDistortion is a lot more clear and probably would not have been your first guess.

The documentation is along side the source for good reason they need to be kept in sync. Document and code simultaneously. If you code a feature, document it as you go or better still design the feature by using the documentation then code and document as you go. This way the two are really not that different.