Strategies and Standards

XXX Project




Strategies and Standards




Version: 1.0 




Package Design


Source Code
Packages will have the following layout: com.abc.<project>.<location>.<subsection>
Examples of locations are:  order.single, static.broker, client, etc. 


Subsections are: dao, ejb and util.


Sample packages like: 


com.abc.demo.account.order.dao
com.abc.demo.account.order.ejb


common
Classes and interfaces used by both the server and the client api, i.e. value objects, home interfaces, local and remote interfaces will live under a location called common.  
Possible packages under common:
com.abc.demo.common.dao
com.abc.demo.common.account.domain
com.abc.demo.common.account.ejb
etc. 


Non-demo specific classes
These are non demo specific classes that may be moved into their own SVN repository at a later date.  They will live under:


com.abc.core
JUnit tests


There should be approximately one junit test class for each interface, dao, ejb and util class to test the public and protected methods. 
The package structure will be as follows: 
test.abc.demo.<location>.<subsection>.<src class>Test


Junit system tests will be written to test out the lifecycle of each module of project.  Each link of the lifecycle model (i.e. state transition) should be tested.  System tests will live in test.abc.demo.<location>.systemtest.


SVN directory structure


Under the root directory, there will be the following sub directories: 
application  
/<application>/ear
/<application>/sar
/<application>/ejb
/<application>/cfg
/<application>/bin
where <application> may be demo.appserver or client, etc.


build Destination directory ant targets
classes Destination directory of eclipse build
lib Third party libs to include in jars, etc.
sql Scripts to generate schema.
src
cfg ?not sure about this




Ant tasks
To Do: Review ‘depends’.  
Task Description
assemble-ear Assembles ear files.
assemble-ejb Assembles ejbs.
assemble-sar Assembles sar files.
clean Removes all class files from build directory.
compile Compiles all java files under ~src/com
compile.test Compiles all java files under ~src/test
deploy.all Deploys all ears and sars to appropriate jboss/deploy directory.
deploy.ear Deploys all ears to appropriate jboss/deploy directory. 
deploy.sar Deploys all sars to appropriate jboss/deploy directory.
deploy.jboss Deploys all application server wide settings to appropriate jboss/conf, jboss/lib and jboss/deploy libraries. 
deploy.jboss.log4j Deploys logging classes.
javadoc Builds javadoc.
prepare Creates directory structure necessary for builds and compiles.
release Creates server distribution.
remove.jboss Un-deploys ears and sars.
run.test Runs the junit tests. 


Coding standards


General java file format
1.) Copyright at top: /* Copyright abc Systems Pty.,  Ltd. 2015 */
2.) Package statement on 2nd line.
3.) Import statements start at 4th line.
4.) Class header java doc precedes class/interface statement, with following layout:
/** 
 * <1 line short description>
 * <longer description>
 *
 * @author
 * @version SVN: $Revision$ $Date
 */
5.) Static variables come after the class/interface statement.
6.) Class attributes come, then:
7.) Public methods
8.) Protected methods
9.) Private methods


Attributes & Methods
1.) Documenting the class attributes is up to the discretion of the developer. 
2.) Generally, each attribute will have a get and a set with a comment at the top of the get method.  
3.) Member variables will be lower case and will not have specific notation associated with them.
4.) Const variables will be in all upper-case with underscores (where appropriate).
5.) Public and protected methods should have Java doc comments with the following format: 
/**
<general description>
@param …
@param … 
@throws …
*/


6.) The developer can add @return statements to method Java docs if fit. 
7.) Generally, a method should not exceed 40 lines. 
8.) The method declaration should take one of the two following formats: 
<scope> <return type> <name>(param1, … paramN) throws Throwable1, … ThrowableN
<scope> <return type> <name>(param1,
param2, 
…,
paramN) throws Throwable1, … ThrowableN
9.) Most methods will throw unchecked exceptions as opposed to checked exceptions.  When a check exception is thrown by a method, any code that calls the method must write a try-catch block to catch the exception.


Other
1.) Line length will be 120 characters.
2.) Indents will be 4 characters long.  
3.) Double indents will be used for continuing lines. 
4.) Opening brackets will start on a separate line (this convention is more commonly used in C++ than Java).
5.) Closing brackets will have their own line. 
6.) Interfaces will start with ‘I’.
7.) Session beans will end in ‘SB’. 
8.) Message driven beans will end in ‘MDB’.
9.) Local interfaces will end with Local and LocalHome.
10.) Remote interfaces will end with Remote and RemoteHome. 




Logging 


1.) Log4j will be used.
2.) The toString() method of each class will print only the primary key information. 
3.) The prettyPrint(String separator) of each class will print all class attributes. 
4.) The level of logging will be checked attempting to log something at debug.
Example:
if(logger.isDebugEnabled()){
Logger.debug(“Received order ” + order.prettyPrint()); 
}


will save on performance when maximum level of logging is WARN. 


The following lines, however, may be overkill: 
if(logger.isDebugEnabled()){
Logger.debug(“Number orders received: “+numOrders); 
}


In this case, 
logger.debug(“Number orders received: “+numOrders); 
Should be sufficient.
5.) It is assumed that INFO will be the level of logging used at production. 
The following items will be logged at info:
a. User requests & details as they come into the system. (demo.log)
b. Server requests & details just before they are sent to the broker.(demo_fix.log)
c. Broker responses & primary key data as they enter the system. (demo_fix.log)
d. Server responses & details just before they are sent the client. (demo.log)  
6.) Debug logging is up to the discretion of the developer.