Changes between Version 7 and Version 8 of DeveloperGuidelines
- Timestamp:
- 08-02-11 14:11:48 (3 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
DeveloperGuidelines
v7 v8 2 2 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 [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 3 4 = Documentation=4 == Documentation == 5 5 For 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 6 7 == SVN Keyword Expansion / Substitution==7 === SVN Keyword Expansion / Substitution === 8 8 All 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: 9 9 {{{ … … 23 23 }}} 24 24 25 == Descriptions==25 === Descriptions === 26 26 27 === First Sentence===27 ==== First Sentence ==== 28 28 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. 29 29 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.": … … 65 65 }}} 66 66 67 == Tag Conventions==67 === Tag Conventions === 68 68 69 === Order of Tags===69 ==== Order of Tags ==== 70 70 Include tags in the following order: 71 71 {{{ … … 81 81 }}} 82 82 83 === Ordering Multiple Tags===83 ==== Ordering Multiple Tags ==== 84 84 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. 85 85 … … 112 112 }}} 113 113 114 === Required Tags===114 ==== Required Tags ==== 115 115 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.) 116 116 117 117 These principles expedite automated searches and automated processing. Frequently, too, the effort to avoid redundancy pays off in extra clarity. 118 118 119 === Tags===119 ==== Tags ==== 120 120 All 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. 121 121 * [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#@author @author] … … 127 127 * [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#@version @version] 128 128 129 = Indentation=129 == Indentation == 130 130 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: 131 131 132 132 [[Image(IntelliJIndentation1.png)]] 133 133 134 = Naming convention=134 == Naming convention == 135 135 All variables, classes, functions and methods use the [http://en.wikipedia.org/wiki/CamelCase Camel Casing] naming convention. 136 136 … … 143 143 Note: while class names start with an uppercase character, instances of classes are variables and hence start with a lowercase charact 144 144 145 = Javascript=145 == Javascript == 146 146 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. 147 147 148 = Icons=148 == Icons == 149 149 For 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).
