Changes between Initial Version and Version 1 of DeveloperGuidelines


Ignore:
Timestamp:
Feb 8, 2011, 10:33:04 AM (9 years ago)
Author:
jannekevdp@…
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • DeveloperGuidelines

    v1 v1  
     1=Developer Guidelines=
     2The 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 [http://www.grails.org Grails]. Note that I tend to use ([http://developer.yahoo.com/yui/compressor/ yui compressed]) minified Javascript and css for the production version of the application using an if statement.
     3
     4=Documentation=
     5For documentation we follow the [http://java.sun.com/j2se/javadoc/writingdoccomments/ 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.
     6==SVN Keyword Expansion / Substitution==
     7All files should contain revision information using SVN [http://svnbook.red-bean.com/en/1.4/svn.advanced.props.special.keywords.html SVN Keyword Expansion / Keyword Substition] (svn:keywords Date Rev Author). Example lines to include in the documentation:
     8{{{
     9<source lang="java">
     10/**
     11  ... regular doc ...
     12  *
     13  * Revision Information:
     14  * $Author$
     15  * $Date$
     16  * $Rev*
     17  */
     18</source>
     19}}}
     20Keyword 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:
     21{{{
     22<code>
     23$ svn propset svn:keywords "Date Author Rev" myClass.groovy
     24</code>
     25}}}
     26==Descriptions==
     27===First Sentence===
     28The 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.
     29This 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.":
     30{{{
     31<source lang="groovy">
     32/**
     33  * This is a simulation of Prof. Knuth's MIX computer.
     34  */
     35</source>
     36}}}
     37However, you can work around this by typing an HTML meta-character such as "&" or "<" immediately after the period, such as:
     38{{{
     39<source lang="groovy">
     40/**
     41  * This is a simulation of Prof.&nbsp;Knuth's MIX computer.
     42  */
     43</source>
     44}}}
     45or
     46{{{
     47<source lang="groovy">
     48/**
     49  * This is a simulation of Prof.<!-- --> Knuth's MIX computer.
     50  */
     51</source>
     52}}}
     53In particular, write summary sentences that distinguish overloaded methods from each other. For example:
     54{{{
     55<source lang="groovy">
     56/**
     57  * Class constructor.
     58  */
     59  foo() {
     60   ...
     61   
     62/**
     63  * Class constructor specifying number of objects to create.
     64  */
     65  foo(int n) {
     66   ...
     67</source>
     68}}}
     69==Tag Conventions==
     70===Order of Tags===
     71Include tags in the following order:
     72<source lang="java">
     73* @author      (classes and interfaces only, required)
     74* @version     (classes and interfaces only, required. See footnote 1)
     75* @param       (methods and constructors only)
     76* @return      (methods only)
     77* @exception   (@throws is a synonym added in Javadoc 1.2)
     78* @see         
     79* @since       
     80* @serial      (or @serialField or @serialData)
     81* @deprecated  (see How and When To Deprecate APIs)
     82</source>
     83
     84===Ordering Multiple Tags===
     85We 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.
     86
     87Multiple @author tags should be listed in chronological order, with the creator of the class listed at the top.
     88
     89Multiple @param tags should be listed in argument-declaration order. This makes it easier to visually match the list to the declaration.
     90
     91Multiple @throws tags (also known as @exception) should be listed alphabetically by the exception names. 
     92
     93Multiple @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.
     94<source lang="java">
     95   @see #field
     96   @see #Constructor(Type, Type...)
     97   @see #Constructor(Type id, Type id...)
     98   @see #method(Type, Type,...)
     99   @see #method(Type id, Type, id...)
     100   @see Class
     101   @see Class#field
     102   @see Class#Constructor(Type, Type...)
     103   @see Class#Constructor(Type id, Type id)
     104   @see Class#method(Type, Type,...)
     105   @see Class#method(Type id, Type id,...)
     106   @see package.Class
     107   @see package.Class#field
     108   @see package.Class#Constructor(Type, Type...)
     109   @see package.Class#Constructor(Type id, Type id)
     110   @see package.Class#method(Type, Type,...)
     111   @see package.Class#method(Type id, Type, id)
     112   @see package
     113</source>
     114===Required Tags===
     115An @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.)
     116
     117These principles expedite automated searches and automated processing. Frequently, too, the effort to avoid redundancy pays off in extra clarity.
     118===Tags===
     119All Per-tag documentation can be found [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html here], or more quickly for some frequently used tags directly via the anchors listed below.
     120* [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#@author @author]
     121* [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#@param @param]
     122* [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#@return @return]
     123* [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#@see @see]
     124* [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#@since @since]
     125* [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#@throws @throws]
     126* [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#@version @version]
     127
     128=Indentation=
     129All 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:
     130
     131[[Image:IntelliJIndentation.png]]
     132
     133=Naming convention=
     134All variables, classes, functions and methods use the [http://en.wikipedia.org/wiki/CamelCase CamelCasing] naming convention.
     135
     136{| class="wikitable" style="border:1px solid black;vertical-align: baseline;"
     137|-
     138! Identifier Type
     139! Rules for Naming
     140! Examples
     141|-
     142| Classes
     143| 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).
     144| class Raster;
     145class ImageSprite;
     146|-
     147| Methods
     148| Methods should be verbs, in mixed case with the first letter lowercase, with the first letter of each internal word capitalized.
     149| run();
     150runFast();
     151getBackground();
     152|-
     153|Variables
     154|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.
     155
     156Variable 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.
     157|int             i;
     158char            c;
     159float           myWidth;
     160|}
     161
     162Note: while class names start with an uppercase character, instances of classes are variables and hence start with a lowercase charact
     163
     164=JavaScript=
     165In 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.
     166=Icons=
     167For consistency we stick with using icons from the widely used [http://www.famfamfam.com/archive/silk-icons-thats-your-lot/ 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).
     168
     169
     170[[Category:DBNP]]