Changes between Initial Version and Version 1 of Coding Standards

Timestamp:

01/15/14 17:26:12 (12 years ago)

Author:

zmanchun

Comment:

--

Coding Standards

@@ +1 @@
+
+== Coding Standards ==
+
+- General
+
+1. All code should compile without errors or warnings;
+2. Eclipse should indicate no warnings.
+
+- Code Structure
+
+1. source code goes in src (under trunk)
+2. test code goes in test (under trunk)
+3. never use wildcards (*) in import statements
+4. a class should do one thing and do that one thing well
+    - keep them small
+    - break up into smaller classes if class becomes unwieldy
+5. break up a method into smaller pieces if it gets too long
+6. place one blank line between elements in a file (an element is a field, method, or class)
+7. all local variables declared in a block (i.e., a compound statement in curly braces) should appear at the top of the block, followed by a blank line, followed by the statements in that block; this greatly enhances readability
+
+- Visibility
+1. think carefully about the visibility level for each element, i.e., whether to make the element public (visible to all), protected (visible to package and sub-classes), package-private (visible to package, the default in Java), or private (visible to same class only)
+2. do not reveal more than absolutely necessary
+3. example: typically constructors can be package-private
+    - a public factory method is called by outside world
+4. best to start at most restrictive (private) and only increase visibility if there is no choice
+5. generally, fields should be private
+    - write access methods for those that need to be revealed
+6. methods declared in (Java) interfaces must be public so don't declare them to be (i.e., leave out the public)
+
+- Names
+1. generally, package names are all lower case letters
+    - exception: IF
+2. class and interface names start with uppercase letters and are written in {{{CamelCase}}}
+3. method and variable names generally start with lower case letters and are written using {{{camelCase}}}
+    - exception: "constants" generally all caps:
+         - {{{public final static int MEM_BOUND = 2060;}}}
+    - exception: names of enum elements:
+         - {{{public enum Result {YES, NO, MAYBE};}}}
+4. avoid abbreviations in identifiers
+    - For example "expression", not "expr"
+    - use meaningful names for identifiers that explain their purpose
+
+- Documentation
+
+1. See [http://docs.oracle.com/javase/7/docs/api/] for good examples of javadocs
+2. See [http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html]
+3. every element (method, field, class, interface, ...) has a javadoc
+4. javadocs should ''explain''
+    - ask yourself ''would someone who has never seen this code before be able to read this and understand what it does?''
+5. tags
+    - which tags occur in javadocs is not nearly as important as the clarity and completeness of the explanation
+    - do not include a tag with no information associated to it
+    - do include an {{{@author}}} tag for each file
+    - do include an {{{@exception}}} tag for each exception (including runtime exceptions) that could be thrown
+6. javadocs for interface methods should not reveal implementation details
+7. javadocs for methods in a class that implement a method declared in an interface can simply refer to the interface javadoc and add any additional information specific to that implementation; do not copy and paste the interface javadoc
+8. method javadocs should list the pre-conditions and post-conditions for the method
+    - a pre-condition is a condition the program state should satisfy when the method is called.  This is typically a condition on the parameters to the method, e.g., {{{N>0}}}.
+    - a post-condition is a guarantee: it states a condition the program state must satisfy when the method returns (assuming the method was called in a way that satisfied the pre-condition)
+9. packages should have a javadoc in a file {{{package-info.java}}}