Production Coding Standards

From ETaxonomy

Jump to: navigation, search

Contents

Documentation/Coding Standards

These are the coding standards, conventions, and engineering practices for developing the production FilteredPush software.

Building

  • No generated files in SVN
  • Always possible to generate without eclipse

Logging

  • Use log4j for logging in Java. (auto generated(?) in eclipse).

Code documentation

  • Use javadoc format for class and method documentation.
  • Include SVN annotations in files. Note that $Author$ is the author of the svn change, which might not be the @author. See also svnAutoConf
  • Files should include the following documentation (embed in templates): 
        Date created.  
	Copyright statement.
	License.
	@ see
	@ author (Author(s)) [all names spelled out in full]
	SVN annotations  $Date, $Author, $Rev, $Id.
 	* File last changed on $Date:$ by $Author:$ in $Rev:$.
	* $Id:$
  • At least $Id$ should be available programmatically from the class: 
static final String classID= "$Id$";
...
public static String getClassID() {
     return classID;
}
  • Classes/interfaces (again, embed in templates) 
	/** classname  summary sentence, purpose, patterns, relationship to other classses, example(s) of use including <code></code> blocks, role in APIs, stability  **/
  • Public constants, attributes 
	   /** description  **/
  • Non-trivial public methods 
	          /** method name summary sentence, purpose, uses, limitaions, error handling
                  * do not merely rephrase the method name, but rather provide additional information
                  * @param  for each parameter
                  * @returns
                  * @throws
                  **/
  • If relevant, particularly in public APIs, use @since (version) and @deprecated
  • Overloaded methods must have summary sentences that distinguish them from each other.
  • Trivial public methods, defined as get, set, is[boolean] that only set or return the value of a private attribute don't need specific documentation.

Unit Tests

  • Provide unit tests for every non-trivial method.
  • Unit tests must include fuzzing tests that demonstrate how the method handles extreme, edge, and attack values (e.g. methods that take an integer value as a parameter should demonstrate the behavior of the method for 0, maxint, maxint+1, minint, minint -1).
  • Methods that throw exceptions must include unit tests that test both the cases of values that are expected to throw exceptions and methods that are expected not to throw exceptions.

Components

  • Each component must include documentation and software engineering artifacts (e.g. UML class diagrams, sequence diagrams) that document the design of the component and provide an overview of the component for a programmer who is.
  • Each API to a component must be documented for programmers who might wish to code to that API.
  • Components can use the javadoc package.html file to document APIs as part of the generated javadocs, see http://java.sun.com/j2se/javadoc/writingdoccomments/#packagecomments for a template.

Repository commits

  • Each commit should relate to a single issue.
  • Document the bug tracking issue, the nature of the problem, and the details of the solution in each commit.
  • Commit messages must use the format “ISSUE /n PURPOSE /n DESCRIPTION” where issue is a cross reference to the bug, purpose is an overview of the intent of the commit and the description includes details of the change.
  • Repository organization
    • Trunk
      • {Component}
    • Tags
      • Use tags if no evolution is expected.
        • (e.g. {Component}6MonthRC1)
        • (e.g. {Component}LastRevBeforeMoveToSourceForge)
    • Branches
      • Use branches if evolution is expected.
    • VendorBranches
      • Use vendor branches to include source of software packages that we are modifying outside their normal repositories (e.g. Specify6, IPT), use the vendor branch to checkout unmodified current versions from the vendor's repository, and copy into relevant place in Trunk or Branches to make changes to our code (our changes should never be committed into a vendor branch, only to our separate modified copy in trunk or branches). To merge in an updated version of the vendor's code to our changes, update the checkout from the vendor's repository into the vendor branch, then merge this into the appropriate place in trunk or branches where our changes to the vendor's code are kept.
  • Non-code artifacts
    • Schemas, ontologies, etc.
      • Include SVN annotations $Date, $Author, $Rev, $Id.

. The documentation of the file should include: 

		Date created.  
		Copyright statement.
		License.
		Author(s)  [names spelled out in full, since the svn $Author may be a username]
		File last changed on $Date:$ by $Author:$ in $Rev:$.
                $Id$
  • Document the purpose of the file.
  • Document everything.
    • Information Models. Follow style (subset of IDEFX1) from Phyloinformatics 7.
      • Entity-relationship diagram
      • List of all relationship cardinalities
      • Document each entity and attribute
        • Entities
          • Definition
          • Comment
          • See Also
        • Attributes
          • Definition
          • Domain
          • Business Rules [required; automatic, semi-manual, manual;
          • Example values
          • Comment

Code formatting

  • Use templates and set up your development environment to use these formats.

Java and PHP

  • Use spaces to indent. Indentation is 4 spaces.
  • Where to put braces and whitespace in method calls 
int foo()
{
    if ( true ) // indentation: 4 spaces
    {
        foo();  // no space between () and ;
    }
    else
    {
        int bar = foo( a, b, c );
    }
}
  • Where to put whitespace in control structures 
for ( int i=0; i<10; i++ )
{
    // do stuff
}
  • One line if statements version 1, acceptable form when condition and conditional block are short. 
if ( true ) foo();  // this is OK
  • One line if statements version 2, preferred form when condition or conditional block are short, or when expansion of the conditional block is anticipated. 
if ( true )         // this is OK too
{
    foo();
}
  • One line if statements versions not to use: 
if ( true )         // this is NOT OK
    foo();
if ( true ) { foo(); }  // this is NOT OK

In general, blocks start and end with lines that only contain { and }.

XML

  • Space before close of empty element 
<a />

User Turtle and Manchester for human readable rdf documents, but use RDF/XML for normative documents.

JSF

Use standard namespace abbreviations for JSF namespaces, e.g. h for http://java.sun.com/jsf/html and f for http://java.sun.com/jsf/core Where to put input values 

<h:input value=”#{abc}” />
<h:outputText value=”abc” />
<h:input value="#{abc}">
    <f:validator  ... />
</h:input>

That is, put input values as values, not between tags.

SQL DDL

Avoid embedding SQL in Java. Use external configurations for SQL rather than embedding SQL queries in Java code. Push any SQL in Java to very limited back end pieces. Structure (use lower case for SQL reserved words and case sensitive table names). 

create table Foo (          
    FooID bigint primary key,       
    fieldname vachar( 3 )
);


UML

No matter how encoded (if in some form of text), if the files are under subversion control, they should have a reasonable scheme for displaying the current value of the svn keyword "Id". When first created, they must explicitly be set with 

svn propset svn:keywords "Id" filename [filename]

Keep in mind that you will not see expansion until that is invoked, and it will change only upon commit. svn keywords are expanded only on checkout or other fetch from the repository. Their value is not stored in the repository version of the file.

For those maintained with bouml, the following is the best practice:

  • On diagrams, in the upper right corner put a comment box with the string $Id$
  • On classes, add an attribute svnID with initial value the string "$Id$" (no quotation marks). This is done with right-click on the object in the bouml model panel.

Use extreme care when working with BOUML and SVN. Recommended practice:

  1. Checkout model within Eclipse
  2. SVN Update model
  3. Start BOUML and open model
  4. Make changes in BOUML
  5. Save changes in BOUML
  6. Close project in BOUML
  7. Refresh project in Eclipse
  8. SVN update
    1. If anything merged from repository, open project in BOUML and attempt to generate HTML documentation.
    2. If HTML generation succeeds, project is not corrupt and you can continue. If it fails, start again at step 1 with a fresh checkout from the repository.
    3. Close project in BOUML (to make sure that locks aren't committed).
  9. SVN commit from within Eclipse (to make sure any added files are added).
  10. Resume at step 2.

Ontology Coding and Documentation

See Ontology Coding and Documentation

Retrieved from "http://www.etaxonomy.org/mw/Production_Coding_Standards"
Personal tools
All Hands Meeting