TradamusCodingGuidelines

Tradamus Coding Guidelines

Java Guidelines

Files

A Java file should start with a copyright header of this form:

/*

 * Copyright 2011-2014 Saint Louis University. Licensed under the
 *    Educational Community License, Version 2.0 (the "License"); you may
 * not use this file except in compliance with the License. You may
 * obtain a copy of the License at
 *
 * http://www.osedu.org/licenses/ECL-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an "AS IS"
 * BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 * or implied. See the License for the specific language governing
 * permissions and limitations under the License.
 */

The copyright notice is followed by the package declaration. This is followed by the import statements, which are followed by the class declaration.

Packages

All code goes into sub-packages of edu.slu.tradamus. Multiple levels of packaging beyond the first are discouraged.

Imports appear after the copyright notice. Java JDK imports appear first, followed by imports from third-party libraries, followed by imports from other Tradamus packages. Within each group, imports are ordered alphabetically.

Classes

Class names are camel-case, starting with a capital letter.

The class declaration should be preceded by a JavaDoc comment describing the class, along with an @author annotation.

Within the class declaration the following is the recommended order:

1. private variables

2. constructors

3. methods which operate on the object as a whole, ordered alphabetically

4. methods which operate on another entity, ordered alphabetically by entity
   e.g. deleteChildren() and loadChildren() appear before getEdition()

5. static variables, including static final constants

6. nested classes

Methods

Method names are camel-case, starting with a lower-case letter.

The first component of a method name should be a verb. If the method primarily acts on the object itself, that is sufficient. If the method acts on another entity or on a portion of the object, that should be indicated as part of the method name.
e.g. load() loads this object, but loadChildren() loads this object's children

Variables

Variable names are camel-case, starting with a lower-case letter.

Where part of a name is an abbreviation, it is all upper-case.
e.g. editionID, not editionId; getURL, not getUrl

Member variables get spelled out in full.
e.g. currentEdition, not curEdition

Local variables and parameters can (and should) use shorter names.
e.g. edID for a local variable holding an edition ID

Constants & Enums

Use of static final variables as constants is encouraged.

Constant names and enum values are all upper-case, with components separated by underscores.
e.g. CONFIRMATION_PENDING

Exceptions

Avoid empty catch blocks. If you have an exception which will never be thrown, an empty catch block is allowed, but the exception should be called "ignored" to indicate that you know what you're doing.
e.g.

:::java
   } catch (JsonProcessingException ignored) {
      // Just writing a Map out as a JSON string.
   }

In general, exceptions should be caught at a level where they can meaningfully be reported to the end-user. In Tradamus, they are typically caught in the servlet's doGet() or doPost() method, where HttpServletResponse.sendError() can be called with an appropriate message.

Comments

Yes. JavaDoc comments in particular.

Logging

Use of System.out is to be avoided.

Tradamus uses java.lang.Logging. Where a class needs a logger, it should be declared as follows:
private static final Logger LOG = Logger.getLogger(MyClass.class.getName());

SQL Guidelines

Tables

Table name is the plural form of the entity being stored, in lower case.
e.g. projects, not project

If the table name consists of multiple words, they should be separated by underscores.
e.g. group_members

Keys

Tables generally have an auto-increment primary key called id of type int(11).

Foreign keys are generally linked using the id field of the foreign table, and have the name of the linked entity.
e.g. in the witnesses table, the edition to which the witness belongs is stored in the edition column

Where possible, use constraints to manage foreign key relationships.
e.g. canvasses are linked to pages as follows:
CONSTRAINT `canvas_page` FOREIGN KEY (`page`) REFERENCES `pages` (`id`) ON DELETE SET NULL

Child entities should take advantage of the ON DELETE CASCADE feature to make it easier to clean up.
e.g. each image is the child of a canvas, so the images table has this constraint:
CONSTRAINT `image_canvas` FOREIGN KEY (`canvas`) REFERENCES `canvasses` (`id`) ON DELETE CASCADE

Columns

Column names are in lower case, separated by underscores.
e.g. target_type

Where appropriate, use of enums is encouraged.

Web-app Guidelines

The general approach is resource-based. Each endpoint corresponds to a resource which is being manipulated:

GET /entity/entID retrieves the given entity
POST /entities creates a new entity
POST /entity/entID/children creates a new child
PUT /entity/entID updates the given entity, or creates it if it doesn't already exist
DELETE /entity/entID deletes an entity