Changes between Version 6 and Version 7 of DeveloperGuidelines

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

--

Legend:

Unmodified
Added
Removed
Modified
  • DeveloperGuidelines

    v6 v7  
    1 =Developer Guidelines= 
     1= Developer Guidelines = 
    22The 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. 
    33 
    4 =Documentation= 
     4= Documentation = 
    55For 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. 
    66 
    7 ==SVN Keyword Expansion / Substitution== 
     7== SVN Keyword Expansion / Substitution == 
    88All 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: 
    99{{{ 
     
    2323}}} 
    2424 
    25 ==Descriptions== 
     25== Descriptions == 
    2626 
    27 ===First Sentence=== 
     27=== First Sentence === 
    2828The 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. 
    2929This 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.": 
     
    6565}}} 
    6666 
    67 ==Tag Conventions== 
     67== Tag Conventions == 
    6868 
    69 ===Order of Tags=== 
     69=== Order of Tags === 
    7070Include tags in the following order: 
    7171{{{ 
     
    8181}}} 
    8282 
    83 ===Ordering Multiple Tags=== 
     83=== Ordering Multiple Tags === 
    8484We 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. 
    8585 
     
    112112}}} 
    113113 
    114 ===Required Tags=== 
     114=== Required Tags === 
    115115An @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.) 
    116116 
    117117These principles expedite automated searches and automated processing. Frequently, too, the effort to avoid redundancy pays off in extra clarity. 
    118118 
    119 ===Tags=== 
     119=== Tags === 
    120120All 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. 
    121121 * [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#@author @author] 
     
    127127 * [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#@version @version] 
    128128 
    129 =Indentation= 
     129= Indentation = 
    130130All 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: 
    131131 
    132132[[Image(IntelliJIndentation1.png)]] 
    133133 
    134 =Naming convention= 
     134= Naming convention = 
    135135All variables, classes, functions and methods use the [http://en.wikipedia.org/wiki/CamelCase Camel Casing] naming convention. 
    136136 
     
    143143Note: while class names start with an uppercase character, instances of classes are variables and hence start with a lowercase charact 
    144144 
    145 =Javascript= 
     145= Javascript = 
    146146In 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. 
    147 =Icons= 
     147 
     148= Icons = 
    148149For 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).