Coding Standards and Procedures

Introduction

This page consolidates existing ideas and practices into a coherent whole to be applied to AstroGrid development. By adopting a set manner of working, both in terms of the code developed and the way in which it is managed and tested, the inevitable complexity of a project as broad as AstroGrid will remain manageable. This applies not only to the development effort but also to the support and enhancements which will take place once the initial development is complete – a responsibility that will probably fall upon a different group of software engineers.

Coding Practices

Typically the coding phase of a software project represents around 20-30% of the total effort. High quality code assists in keeping the remaining effort manageable and thus greatly increases the likelihood the project will reach a successful conclusion. Good code is as simple as practical and written in a consistent “house” style. This allows code to be tested and reviewed in the most efficient manner. As with all projects of this size, optimisations will be undertaken at the end of the project. All code will be held in a central Development CVS repository and copied into a central Release repository once certified (see below). The following are useful to consider with respect to coding style regardless of syntax or construction: Make identifier names as meaningful as possible. Avoid using names and identifiers that need to be explained using comment statements. Use local variables and identifiers for local purposes. Avoiding using global definitions unless absolutely necessary. Keep coding simple. Shortcuts, tricky code, and complicated algorithms often conceal errors and drive up maintenance costs.

Standards

There are several coding standards for Java based projects available and it makes little sense to create a new one for AstroGrid. One of the more complete style guides is published by Rogue Wave in a simple and concise format. All team leaders will be given a copy of this standard (a small paperback book entitled “The elements of Java style”) and any code developed from now on should conform largely to these guidelines. Thus it should be easy for developers at one site to examine and quickly understand code developed at another site. This will include cross site code reviews if that is eventually deemed desirable. Code Review Regular code reviews will be undertaken by local teams. These will be driven by individual developers and overseen by the team leader. The format of code reviews is down to individual teams and what they are comfortable with. As a starting point, new or junior developers should have their code regularly reviewed by a senior developer until they are comfortable with the projects requirements. Other code should be reviewed privately, off line and comments returned to the author (copied to all reviewers). Periodic code walk-throughs should be scheduled to ensure all developers are fully familiar with all aspects of code their team is developing. Alternatives to off line code review include the formal code review meeting, but these become ever more difficult to schedule as the release date approaches and can sometimes create an intimidating and counter productive forum unless very carefully managed. To reiterate the “single committer” paradigm:

1. Developer develops the code
2. Developer subjects the newly developed code to unit and/or package tests
3. New code is run from a user perspective (so-called Black Box testing)
4. Developer sends the code to all team members (or a code review meeting takes place as locally defined)
5. Team members comment on code providing feedback on quality and bugs
6. Developer resolves any issues raised and publishes a revision
7. Cycle repeats until all issues resolved
8. Designated committer merges code into the Release CVS repository

A code review is designed to detect errors in the code or in the design, not to correct them. Reviews are also designed to encourage consistent coding practices and most importantly to ensure all team members are at least familiar with the code being developed by their team. This in turn will help prevent redundant or conflicting code being inadvertently developed as well as allow developers to quickly assume responsibility for a code module should that become necessary. Finally, each developer should be sufficiently familiar with the code to allow effective testing and diagnosis to take place (i.e. to determine where a problem lies and who is therefore responsible for a fix). The format and scheduling of code reviews will be the responsibility of individual team leaders, but should be designed to ensure the volume of unreviewed code does not become unmanageable. Experience will dictate which code needs full review and which can safely be skimmed. Code should be reviewed before being entered into the release repository. It goes without saying that code to be reviewed should have successfully passed all unit and/or package tests before the review. Periodically critical code will be reviewed by a wider team from some or all of the other development sites for the reasons outlined above. A separate document has an example [code review] checklist which teams might like to adopt and adapt.

Packaging

Java Naming Conventions

AstroGrid will use industry standard package naming conventions i.e. The root of the fully qualified name for all AstroGrid components will be org.astrogrid.*. Packaging will reflect functionality and adhere to the usual “style” conventions. Releases of Java code will consist of collections of JARS. These JARS will be built from a point as low as possible from within the namespace. Unless other imperatives exist, JARS will be installed to use the Java extension mechanism to keep installation clean and minimise the “foot print” AstroGrid occupies within individual user accounts. Finally, packages should be built according to standard criteria, such as:

• Common reuse
• Common closure
• Reuse/release equivalence
• Acyclic dependency
• Isolation of volatile classes
• Stable dependency
• Stable abstraction

Facilitate Testing

Packages will be accompanied by scripts (automated or manual) to perform package level testing. Local decision making will determine whether or not an individual class is deemed sufficiently complex or critical to warrant individual unit testing. However, all classes within a package must be fully exercised by the package test suite.

Release

Within this context, a “Release” is the complete suite of code and supporting elements required to install and run an instance of AstroGrid without reference to the development environments. Thus a Release will include both code and all non-code related items (docs, HTML pages, configuration builders, installers etc).

Source Control

Code will be held in 2 levels of CVS repositories, Development and Release. The Development repository is for working or experimental code whilst the Release repository is for tested and reviewed code. As is typical with an Open Source style of development, there will be “developers” who have read-only access to the Release repository and “committers” who have read-write access. Typically the committer for each team will be the team leader. Each team is expected to update (merge with) the Release repository at least once a week (Friday afternoon) and preferably more frequently. More frequent commits may be driven by the dependency requirements of other teams. Obviously the committer must ensure only code from their team is merged, regardless of what is held locally. The Release CVS repository will be readable using the “pserver” mechanism and anonymous access. Each commiter will have secure access to CVS. This will be provided either using the “ext:” mechanism and SSH or “pserver:” tunnelled through SSH. Details will be determined by the CVS administrators. Normal security procedures on the CVS system will manage all other security. The structure of the Development CVS repository will mirror the structure of the Release repository, which in turn will match the package naming scheme. This is straightforward to build and maintain. All aspects of the development effort will be held in the repositories. This includes any build and deployment scripts

-- KeithNoddle - 04 Dec 2002