User’s Manual Thomas Jefferson National Accelerator Facility

Appendix A

Clas12 Java coding standards

Packages




Classes


• 
  File name

  
• 
  Date

  
• 
  Author
  
• 
  
Brief description the rationale for constructing the class
  


Example:

/**

* JSA: Thomas Jefferson National Accelerator Facility

* Described in the NOTICE file included as part of this distribution.

* Copyright (c), Aug 13, 2010

*

* It parses setup.xml file to get platform configuration parameters.

* @author Vardan Gyurjyan

* @version 1.3.1

*/

public class AConfig { …}

Variables


Example:

/*

* The current number of elements.

*/

protected int count_;

Methods



• 
  @param paramName description. 

  
• 
  @return description of return value

  
• 
  @exception exceptionName description

  

* Sends input data to the service, which will trigger core engine

* @param containerName Service container name

* @param serviceName Service name

* @param input Input data object

* @param requestId Service request ID for multiple input
* synchronization

* @return Boolean=false if failed

Naming Conventions

• 
  packages: lowercase
  
• 
  classes: Camel notation, i.e. Attached words with the first letter of each word
  
• 
  capitalized.
 Example: CorseTrackFinder
  
• 
  Exception class: Camel notation, where a class name ends with the word Exception. Example: TrackReconstructionException
  
• 
  Interface. (pick one)
Camel notation, where an interface name
  
  • 
    
ends with the word Interface, OR

    
  • 
    ends with Ifc, OR
    
  • 
    
starts with I
    
• 
  constants (finals): UPPER_CASE_WITH_UNDERSCORES

  
• 
  private or protected: (pick one)

  
  • 
    first word lowercase with the trailing underscore_, OR

    
  • 
    prefix with this, OR
    
  • 
    prefix with my
static private or protected: first word lowercase with the two trailing underscores__,
local variables: first word lower case but internal words capitalized
methods: first word lower case but internal words capitalized
    

• 
  Number of spaces to indent.

  
• 
  Left-brace (``{) placement at end of line or beginning of next line.
  
• 
  Maximum line length.
  
• 
  Spill-over indentation for breaking up long lines.

  
• 
  Declare all class variables in one place (by normal convention, at the top of the class).
  

Recommendations


• 
  Avoid using inner classes.
  
• 
  Limit a class size to less than 500 code-lines (including comments).
  
• 
  
Be precise about what you are importing. Check that all declared imports are actually used.
  
• 
  When reasonable, consider writing a main method for the class in each java file. The main method should provide a simple unit test or demo.
  
• 
  If others can implement your class functionality completely differently, define an interface, not an abstract class. Generally, use abstract classes only when they are partially abstract; i.e., they implement some functionality that must be shared across all subclasses.
  
• 
  
Internal data objects passed across services MUST implement Serializable interface

  
• 
  Never declare instance variables as public. Instead provide access (get/set) methods to protected/private variables. Making variables public gives up control over internal class structure.
  
• 
  Minimize statics, except for static final constants.
  
• 
  Prefer long to int, and double to float to avoid arithmetic overflow and underflow.
  
• 
  Avoid giving a variable the same name as one in a superclass.
  
• 
  Prefer declaring arrays as Type[] arrayName rather than Type arrayName[].
  
• 
  
Write methods that perform only single algorithmic operation. In particular, separate out methods that change object state from those that just rely upon it.
  
• 
  
Prefer synchronized methods to synchronized blocks.
  
• 
  
Whenever reasonable, define a default (no-argument) constructor so objects can be created via Class.newInstance().This allows classes of types unknown at compile time to be dynamically loaded and instantiated.

  
• 
  Use the method equals() instead of operator == when comparing objects. In particular, do not use == to compare Strings.
  
• 
  Declare and initialize a new local variable rather than reusing (reassigning) an existing one whose value happens to no longer be used at that program point.
  
• 
  
Assign null to any reference variable that is no longer being used to enable garbage collection.
  

Appendix B

Object model design recommendations

Most likely the service engine developer will be using an object-oriented programming paradigm to develop physics data processing engines. In this appendix we would like to present a set of suggestions that will prevent common mistakes in object-oriented design and programming.

“Has a” versus “Is a” relationship

These two relationships are basic mechanisms for developing object model of a software program. However, the “is a” relationship or inheritance is applicable only in very specific context, and in majority physics data processing algorithm the appropriate choice is a“has a” relationship. In another words, the typical goal of extending responsibilities of a certain class is more suitable by delegating work to other more specialized objects. So, in order to choose a proper relationship we suggest the following two recommendations:

• 
  Use the “has a” relationship to extend duties of a certain class by delegating work to other more appropriate objects.
  
• 
  Use the “is a” relationship if you need to extend the attributes and methods.
  

Take into account though that the “is a” relationship presents a weak encapsulation within a class hierarchy, so it is a good idea to use this mechanism when you really need this kind of relationship.

More on using “is a” relationship

Use this type of object-oriented relationship if the class you are developing

• 
  can be described as “is a special kind of”, not “is a role played by a”
  
• 
  extends rather than overrides or nullifies its superclass
  
• 
  does not extend or subclass a utility class (i.e. always keep methods providing useful functionality in a utility class and do not inherit from it)
  
• 
  Expresses special kind of roles that is a natural extension of the parent class
  

Interface based design

In object-oriented software programs objects interact with other objects to complete a designed algorithm. An interface is a powerful concept in object-oriented programming that makes things pluggable. An interface holds a collection of method signatures (nether description nor any source code behind these method signatures). So, in effect, an interface defines a contract between interacting objects. Interface design is very potent, and unfortunately is often used without through analyses of the software task in consideration. Overuse of this concept will make an object model more complex and abstract.

Contexts in which interfaces help

It is clear that if object connections (i.e. what I know?) and object interactions (who I interact with?) are predefined and they are not going to be changed or expanded, we do not need an interface-based design. However if during the design process we claim that: “we don’t care what kind of object we are interacting with as log as that object provides a functionality in terms of a specific method signature” then we need to design our object model utilizing interfaces.

Interface-based design is used in a variety of scenarios, yet we would like to mention some common cases when interfaces really help.

• 
  Use interfaces to factor out common method signatures to bring a higher level of abstraction to an object model. In another words if you have similar signature methods in multiple classes you consolidate these methods under one interface. This also helps to achieve an overall visual simplification of a code.
  
• 
  Use interfaces if you would like to exercise a so-called proxy strategy. For example, say I am interested in basic characteristics of a detector “hit”. Instead of knowing the object type that deals with the specific detector hit (for example DC hit) one can ask a question to a Hit object (playing a proxy for all detector components) about the basic characteristics of the DC hit. Here we assume that we have common detector hit manipulating methods, and can factor them into the interface that was implemented by the DC hit class.
  
• 
  Use interfaces to embrace future expansions of the object model. We can factor out method signatures and group them in the interface sooner, so objects from different classes and authors can be graciously accommodated in Clas12 software base in the future.
  

References

1. 
   Thomas Erl 2007 SOA: Principles of Service Design (Prentice Hall, ISBN: 0-13-234482-3)
   

2. 
   V. Gyurjyan et.al., CLARA: A contemporary Approach to Physics Data Processing, Journal of Physics Conference Series 331, 032013 (2011)
   

3. 
   C Timmer, et al. cMsg – A General Purpose, Publish-Subscribe, Inter-process Communication Implementation and Framework, Proceedings of the International Conference on Computing in High Energy and Nuclear Physics, Victoria BC, Canada 2007.
   

4. 
   G. Barrand et al., GAUDI: A Software Architecture and Framework for Building HEP Data Processing Applications, Comp. Phys. Commun. 140, 44 (2001).
   

5. 
   E Wolin, et al. EVIO –Lightweight Object-Oriented I/O Package, Proceedings of the IEE NSS, Hawaii, US 2007.
   

Download 415.94 Kb.

Share with your friends: