The DbNP Project contains several Javascript classes which can dynamically add functionality to the pages which are developed. All of these classes rely on the jQuery library so make sure jQuery is available before using any of these classes. Note that I am using the Grails notation of including Javascript as the whole project is built in ​Grails. Note that I tend to use (​yui compressed) minified Javascript and css for the production version of the application using an if statement.

=Documentation= For documentation we follow the ​JavaDoc / Groovydoc standard for documenting classes, methods and functions. In the unlikely event that a file should contain more than one class, the revision information should only be included in the topmost class documentation. ==SVN Keyword Expansion / Substitution== All files should contain revision information using SVN ​SVN Keyword Expansion / Keyword Substition (svn:keywords Date Rev Author). Example lines to include in the documentation:

/**
  ... regular doc ...
  *
  * Revision Information:
  * $Author$
  * $Date$
  * $Rev*
  */

Keyword expansion must be manually defined on a per-file basis. Possibly your SVN IDE integration or stand alone client will be capable of recusively setting these keywords, and you can also do it yourself manually:

$ svn propset svn:keywords "Date Author Rev" myClass.groovy

==Descriptions== ===First Sentence=== The first sentence of each doc comment should be a summary sentence, containing a concise but complete description of the API item. This means the first sentence of each member, class, interface or package description. The Javadoc tool copies this first sentence to the appropriate member, class/interface or package summary. This makes it important to write crisp and informative initial sentences that can stand on their own. This sentence ends at the first period that is followed by a blank, tab, or line terminator, or at the first tag (as defined below). For example, this first sentence ends at "Prof.":

/**
  * This is a simulation of Prof. Knuth's MIX computer.
  */

However, you can work around this by typing an HTML meta-character such as "&" or "<" immediately after the period, such as:

/**
  * This is a simulation of Prof. Knuth's MIX computer.
  */

or

/**
  * This is a simulation of Prof.<!-- --> Knuth's MIX computer.
  */

In particular, write summary sentences that distinguish overloaded methods from each other. For example:

/** 
  * Class constructor.
  */
  foo() {
   ...
    
/**
  * Class constructor specifying number of objects to create.
  */
  foo(int n) {
   ...

==Tag Conventions== ===Order of Tags=== Include tags in the following order:

* @author      (classes and interfaces only, required)
* @version     (classes and interfaces only, required. See footnote 1)
* @param       (methods and constructors only)
* @return      (methods only)
* @exception   (@throws is a synonym added in Javadoc 1.2)
* @see         
* @since       
* @serial      (or @serialField or @serialData)
* @deprecated  (see How and When To Deprecate APIs)

===Ordering Multiple Tags=== We employ the following conventions when a tag appears more than once in a documentation comment. If desired, groups of tags, such as multiple @see tags, can be separated from the other tags by a blank line with a single asterisk.

Multiple @author tags should be listed in chronological order, with the creator of the class listed at the top.

Multiple @param tags should be listed in argument-declaration order. This makes it easier to visually match the list to the declaration.

Multiple @throws tags (also known as @exception) should be listed alphabetically by the exception names.

Multiple @see tags should be ordered as follows, which is roughly the same order as their arguments are searched for by javadoc, basically from nearest to farthest access, from least-qualified to fully-qualified, The following list shows this progression. Notice the methods and constructors are in "telescoping" order, which means the "no arg" form first, then the "1 arg" form, then the "2 arg" form, and so forth. Where a second sorting key is needed, they could be listed either alphabetically or grouped logically.

   @see #field
   @see #Constructor(Type, Type...)
   @see #Constructor(Type id, Type id...)
   @see #method(Type, Type,...)
   @see #method(Type id, Type, id...)
   @see Class
   @see Class#field
   @see Class#Constructor(Type, Type...)
   @see Class#Constructor(Type id, Type id)
   @see Class#method(Type, Type,...)
   @see Class#method(Type id, Type id,...)
   @see package.Class
   @see package.Class#field
   @see package.Class#Constructor(Type, Type...)
   @see package.Class#Constructor(Type id, Type id)
   @see package.Class#method(Type, Type,...)
   @see package.Class#method(Type id, Type, id)
   @see package

===Required Tags=== An @param tag is "required" (by convention) for every parameter, even when the description is obvious. The @return tag is required for every method that returns something other than void, even if it is redundant with the method description. (Whenever possible, find something non-redundant (ideally, more specific) to use for the tag comment.)

These principles expedite automated searches and automated processing. Frequently, too, the effort to avoid redundancy pays off in extra clarity. ===Tags=== All Per-tag documentation can be found ​here, or more quickly for some frequently used tags directly via the anchors listed below.

• ​@author
• ​@param
• ​@return
• ​@see
• ​@since
• ​@throws
• ​@version

=Indentation= All code (Groovy, GSP, Javascript, HTML, Java, etc) should conform to using tabbed indentation. Make sure to set your IDE up accordingly for all of these filetypes. An IntelliJ Example:

=Naming convention= All variables, classes, functions and methods use the ​Camel Casing naming convention.

Identifier Type	Rules for Naming	Examples
Classes	Class names should be nouns, in mixed case with the first letter of each internal word capitalized. Try to keep your class names simple and descriptive. Use whole words-avoid acronyms and abbreviations (unless the abbreviation is much more widely used than the long form, such as URL or HTML).	class Raster;class ImageSprite?;
Methods	Methods should be verbs, in mixed case with the first letter lowercase, with the first letter of each internal word capitalized.	run(); runFast(); getBackground();
Variables	Except for variables, all instance, class, and class constants are in mixed case with a lowercase first letter. Internal words start with capital letters. Variable names should not start with underscore _ or dollar sign $ characters, even though both are allowed. Variable names should be short yet meaningful. The choice of a variable name should be mnemonic- that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary "throwaway" variables. Common names for temporary variables are i, j, k, m, and n for integers; c, d, and e for characters.	int i; char c; float myWidth;

Note: while class names start with an uppercase character, instances of classes are variables and hence start with a lowercase charact

=Javascript= In this project only the jQuery library (and libraries extending jQuery's functionality like jQuery-ui) may be used to reduce clutter, overhead and conflicts. Therefore: refrain from installing plugins containing other Javascript libraries (like mootools, prototype, yui, etc) as these will not be allowed. =Icons= For consistency we stick with using icons from the widely used ​famfamfam silk icon set and they are stored in <code>gscf/web-app/images/icons/famfamfam</code>. Not all icons are stored in that folder by default, so add the icons you require yourself if they are not present. In the rare occasion that an icon is not available or does not satisfy the needs, you may add icons to <code>gscf/web-app/images/icons/</code> but try to keep them consistent (16 x 16 pixels).