Recent changes to TradamusCodingGuidelines

TradamusCodingGuidelines modified by Domhnall101

Domhnall101 — Tue, 06 Oct 2015 20:07:08 -0000

--- v3
+++ v4
@@ -1,6 +1,8 @@
-## Java Guidelines ##

-### Files ###
+##Tradamus Coding Guidelines
+### Java Guidelines ##
+
+#### Files ###
 A Java file should start with a copyright header of this form:

 ~~~~
@@ -22,12 +24,12 @@

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

-### Packages ###
+#### 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 ###
+#### 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.
@@ -47,13 +49,13 @@

 6. nested classes

-### Methods ###
+#### 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 ###
+#### 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.
@@ -65,13 +67,13 @@
 Local variables and parameters can (and should) use shorter names.
 e.g. `edID` for a local variable holding an edition ID

-### Constants & Enums ###
+#### 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 ###
+#### 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.

@@ -84,25 +86,25 @@

 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 ###
+#### Comments ###
 Yes.  JavaDoc comments in particular.

-### Logging ###
+#### 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 ##
+### SQL Guidelines ##

-### Tables ###
+#### 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 ###
+#### 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.
@@ -116,13 +118,13 @@
 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 ###
+#### Columns ###
 Column names are in lower case, separated by underscores.
 e.g. `target_type`

 Where appropriate, use of enums is encouraged.  

-## Web-app Guidelines ##
+### 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

Tradamus Coding Guidelines modified by Eric Smith

Eric Smith — Tue, 17 Jun 2014 20:31:54 -0000

--- v2
+++ v3
@@ -20,7 +20,7 @@
  */
 ~~~~

-The copyright notice is followed by the package declaration.  This is followed by the import statements, which is followed by the class declaration.
+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.
@@ -30,6 +30,8 @@
 ### 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
@@ -38,7 +40,7 @@

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

-4. methods which operate on another entity, ordered by entity.
+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

Tradamus Coding Guidelines modified by Eric Smith

Eric Smith — Tue, 17 Jun 2014 20:29:44 -0000

--- v1
+++ v2
@@ -22,6 +22,14 @@

 The copyright notice is followed by the package declaration.  This is followed by the import statements, which is 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.
+
 Within the class declaration the following is the recommended order:

 1. private variables
@@ -36,14 +44,6 @@
 5. static variables, including static final constants

 6. nested classes
-
-### 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.

 ### Methods ###
 Method names are camel-case, starting with a lower-case letter.
@@ -60,13 +60,13 @@
 Member variables get spelled out in full.
 e.g. `currentEdition`, not `curEdition`

-Local variables and parameters should use shorter names.
-e.g. `edID` for an edition ID
+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.

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

 ### Exceptions ###
@@ -91,7 +91,7 @@
 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 Standards ##
+## SQL Guidelines ##

 ### Tables ###
 Table name is the plural form of the entity being stored, in lower case.
@@ -106,13 +106,21 @@
 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 Standards ##
+## 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

Tradamus Coding Guidelines modified by Eric Smith

Eric Smith — Tue, 17 Jun 2014 20:09:39 -0000

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 is followed by the class declaration.

Within the class declaration the following is the recommended order:

private variables
constructors
methods which operate on the object as a whole, ordered alphabetically
methods which operate on another entity, ordered by entity.
e.g. deleteChildren() and loadChildren() appear before getEdition()
static variables, including static final constants
nested classes

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.

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 should use shorter names.
e.g. edID for an edition ID

Constants & Enums

Use of static final variables as constants is encouraged.

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.

   } 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 Standards

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

Columns

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

Where appropriate, use of enums is encouraged.

Web-app Standards

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