Programming Playground Rules

This page is based on the initial blog posting from June 5, 2008 and updated based on additional developments. This will be the place where the NCPHI Lab's and eventually the PHGrid's programming conventions and policies are captured:

Use Sourceforge Subversion site to store changes - All changes are checked into the Subversion site on the sourceforge project. Only security related changes (passwords, etc) are not checked in, and these are factored out into a property or configuration file.

Everything builds - Maven is used to build (compile and package) and deploy changes. This will allow for changes to be made on different desktops without spending time trying to manually configure a new environment. This also means that if the build breaks then the developer who broke it needs to fix it as soon as possible.

Follow the Sun Code Conventions for Java. These are old, but still applicable for what we're trying to do. We picked this sort of as a default and this can change based on feedback and practice, but we want some uniform style to the project.

Document code- document code to improve clarity. Use javadocs where necessary. This is not documentation for documentation's sake, but enough so that someone coming across the code will be able to follow. This doesn't absolve a programmer from clean, concise coding but should improve on the clarity of a source file.

Write a Use Case first- the first step to development should be to make a post on this blog describing the use case. Nothing too formal, just a description of the steps, who will perform them, alternate flows and error handing. This will provide a way to capture the requirements before any code is written.

Next write a Test Case before coding- after the use case is posted and there's some sort of agreement, then a test case is written while the coding is performed. This speeds up development by institutionalizing testing in a standard manner.

Each project will have a separate folder in the sourceforge root with a Maven pom.xml file for the build (including dependencies).

All properties are stored in a configuration file to allow for projects to be easily built for various target environments. Actual values are not checked into sourceforge as these property values are likely sensitive (server names, passwords, etc.). For example a project named foo would build based on the properties stored in foo.properties. The file checked into SVN would be named foo.properties.template and contain descriptions for each of the properties, but not values. When a developer is building, they will take the proeprties file as configured for an environment, rename it to foo.properties and run their build. It is likely that you will have foo-dev.properties, foo-training.properties, foo-staging.properties, foo-production.properties (none checked into SVN) and choose a properties file based on where your deployment is targeted.

All changes are tracked using the SourceForge tracker for Bugs and Feature Requests. This is done to project project transparency to all our changes and prioritization of changes.

Every Friday, the current project state is built to the training node (ncphi.phgrid.net) so that the community can see progress and comment. Eventually, our CM processes will be run nightly and deployed more frequently than once a week.

Each evening, before leaving each developer ensures that their changes adhere to these rules and checks them into SVN.