Changes between Version 5 and Version 6 of DeveloperGuidelines

Show
Ignore:
Timestamp:
08-02-11 10:54:44 (3 years ago)
Author:
jannekevdp@…
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • DeveloperGuidelines

    v5 v6  
     1=Developer Guidelines= 
    12The 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. 
    23 
    34=Documentation= 
    45For 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 
    57==SVN Keyword Expansion / Substitution== 
    68All 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: 
     
    2224 
    2325==Descriptions== 
     26 
    2427===First Sentence=== 
    2528The 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. 
     
    6366 
    6467==Tag Conventions== 
     68 
    6569===Order of Tags=== 
    6670Include tags in the following order: 
     
    107111   @see package 
    108112}}} 
     113 
    109114===Required Tags=== 
    110115An @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.) 
    111116 
    112117These principles expedite automated searches and automated processing. Frequently, too, the effort to avoid redundancy pays off in extra clarity. 
     118 
    113119===Tags=== 
    114120All 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.