Changes between Version 1 and Version 2 of DeveloperGuidelines


Ignore:
Timestamp:
Feb 8, 2011, 10:46:42 AM (7 years ago)
Author:
jannekevdp@…
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • DeveloperGuidelines

    v1 v2  
    66==SVN Keyword Expansion / Substitution==
    77All 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 {{{
    98<source lang="java">
    109/**
     
    1716  */
    1817</source>
    19 }}}
    2018Keyword 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 {{{
    2219<code>
    2320$ svn propset svn:keywords "Date Author Rev" myClass.groovy
    2421</code>
    25 }}}
     22
    2623==Descriptions==
    2724===First Sentence===
    2825The 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.
    2926This 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 {{{
    3127<source lang="groovy">
    3228/**
     
    3430  */
    3531</source>
    36 }}}
     32
    3733However, you can work around this by typing an HTML meta-character such as "&" or "<" immediately after the period, such as:
    38 {{{
     34
    3935<source lang="groovy">
    4036/**
     
    4238  */
    4339</source>
    44 }}}
     40
    4541or
    46 {{{
     42
    4743<source lang="groovy">
    4844/**
     
    5046  */
    5147</source>
    52 }}}
     48
    5349In particular, write summary sentences that distinguish overloaded methods from each other. For example:
    54 {{{
    5550<source lang="groovy">
    5651/**
     
    6661   ...
    6762</source>
    68 }}}
     63
    6964==Tag Conventions==
    7065===Order of Tags===
     
    118113===Tags===
    119114All 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]
     115 * [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#@author @author]
     116 * [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#@param @param]
     117 * [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#@return @return]
     118 * [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#@see @see]
     119 * [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#@since @since]
     120 * [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#@throws @throws]
     121 * [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#@version @version]
    127122
    128123=Indentation=
    129 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:
     124All 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:
    130125
    131 [[Image:IntelliJIndentation.png]]
     126[[Image(IntelliJIndentation1.png)]]
    132127
    133128=Naming convention=
    134 All variables, classes, functions and methods use the [http://en.wikipedia.org/wiki/CamelCase CamelCasing] naming convention.
     129All variables, classes, functions and methods use the [http://en.wikipedia.org/wiki/CamelCase Camel Casing] naming convention.
    135130
    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;
    145 class 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();
    150 runFast();
    151 getBackground();
    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.
     131||'''Identifier Type'''||'''Rules for Naming'''||'''Examples'''||
     132||Classes||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).||class Raster;class ImageSprite;
     133||Methods|| Methods should be verbs, in mixed case with the first letter lowercase, with the first letter of each internal word capitalized.|| run(); runFast(); getBackground();
     134||Variables|| 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. Variable 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.||int             i; char            c; float           myWidth;||
    155135
    156 Variable 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;
    158 char            c;
    159 float           myWidth;
    160 |}
    161136
    162137Note: while class names start with an uppercase character, instances of classes are variables and hence start with a lowercase charact