Coding Practices

Conventions

Classes which manage UI code should not extend swing classes

It is common in Java tutorials for UI classes to extend Java swing classes such as JPanel, JDialog and JMenuItem. However, often it is better for a class to have an instance of a Swing class rather than extend it through inheritance. One of the benefits of using this practice is that the generated JavaDocs are simpler.

Avoid using Singleton patterns that rely on static methods to return a single factory instance.

Any class found in packages *.presentationLayer.* which manages UI code should not extend swing classes such as JPanel or JMenuItem

Naming Conventions

Package naming conventions

classes in packages marked cst.common.* are used in both the administration tool and the logging tool.
classes in packages marked cst.loggingTool.* are used to create the logging tool
classes in packages marked cst.adminTool.* are used to create the administration tool
classes in packages marked cst.common.businessLayer represent the main application concepts. This package contains most of the code used to validate and detect changes in activity data records
classes in packages marked *.persistenceLayer.* are used to manage data either in an in-memory database or a MySQL database. All the SQL queries will be found in these classes.
classes in packages marked *.presentationLayer.* are used to manage the GUIs in the logging and administration tools.
classes in the cst.common.system package are used throughout the code base.
packages marked *.io contain classes which are used to read data to and from tab-delimited text files.
the cst.util package contains general purpose classes which do not depend on any of the main application concepts
the cst.test package contains all the automated test suites used to test the LoggingServiceAPI and AdminServiceAPI

Class Naming Conventions

classes named Production* are used to support operations for the MySQL database.
classes named Demonstration* are used to support operations for the in-memory database.
classes named *Error* and CSTException are part of CST's exception handling system.
classes in cst.loggingTool.io have corresponding classes with similar names in cst.adminTool.io
classes named *API are major public interfaces used by client applications. Interfaces include those relating to the logging tool, the admin tool and plugins.
classes named Abstract* are abstract classes
classes named *Command are menu filter options and follow the Command pattern

Method Naming Conventions

methods named set* set a property. Most of these methods are auto-generated using the IDE.
methods named get* get a property. Most of these methods are auto-generated using the IDE.
methods named is* return a boolean value.
methods named check* are typically validation methods.

Variable Naming Conventions

constants appear in all upper case letters. Words are separated by underscores.

Coding Conventions within Class Files

Each class file follows the following template:
1. the package to which the class belongs
2. class description and licensing agreement notice
3. a code road map which shows the sub-headings that are used to organise methods. Each method that is added to a class is classified using these headings arranged in decreasing order of priority: Constants, Properties, Construction, Override, Interfaces, Errors and Validation, Accessors and Mutators
4. The Construction section contains the constructor methods. For classes which produce user interfaces, the section also includes methods used to create panels, buttons, scroll bars and other components.
classes do not contain any hard-coded strings which appear to application users. All messages are managed in the file CSTProperties.properties.

Author: Kevin Garwood