Changes between Version 5 and Version 6 of DeveloperGuidelines
- Timestamp:
- Feb 8, 2011, 10:54:44 AM (10 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
DeveloperGuidelines
v5 v6 1 =Developer Guidelines= 1 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. 2 3 3 4 =Documentation= 4 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 5 7 ==SVN Keyword Expansion / Substitution== 6 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: … … 22 24 23 25 ==Descriptions== 26 24 27 ===First Sentence=== 25 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. … … 63 66 64 67 ==Tag Conventions== 68 65 69 ===Order of Tags=== 66 70 Include tags in the following order: … … 107 111 @see package 108 112 }}} 113 109 114 ===Required Tags=== 110 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.) 111 116 112 117 These principles expedite automated searches and automated processing. Frequently, too, the effort to avoid redundancy pays off in extra clarity. 118 113 119 ===Tags=== 114 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.
