Coding Guidelines

Coding Style Guidelines

• Review will be done AFTER code is checked into the master branch in the relevant commit/push

• Comments in the review must be fixed on the commit after the review is completed

• These commit/push #s will be provided to the customer

• Must be reviewed by at least one member who did not write the code

• Code Review will be done on GitHub in the master branch under the relevant commit

• Comments will be inline in GitHub and may be done in-person or just by another person

• Must have name of reviewer(s) and name of author (can be in header)

• Must have consistent indentation

• Always examine for clarity of code and formatting (Can add checks on efficiency, redundancy, and security if you notice anything)

• Code does not require comments if readable

Example Class

1. Header at the top of each file containing metadata: project name, author, version, due date, etc. (may be under package and imports)

2. Package and import statements

3. Class declaration with superclass and all important interfaces

4. Static variable, class constants, class fields

5. Most important constructor, less important constructors, any private methods used by constructors

6. Any static methods, any private methods used by the static methods

7. Any important mutators (setters) that changes state of the class, any private methods used by mutators

8. Any important accessors (getters) that returns information of the state of the class, any private methods used by assessors

9. Any methods for convenience, such as equals, clone, toString

10. Any inner classes

    • All non-static fields should be initialized in constructor

    • All classes, fields and methods should have appropriate visibility specifiers (private/public/protected)

    • Naming convention: ClassName, STATIC_FIELD_NAME, CLASS_CONSTANT_NAME, fieldName, methodName, variableName, someVeryLong_variableName

    • All public methods use javadoc comment, all private method uses //

    • All in-line comments use //, aligned within a method when possible

    • Comments for fields and variables use //, next to declaration, aligned vertically if possible

Example class (need not follow formatting exactly):

/**
 * CSE 403 AA
 * Homework #6
 * Due Friday May 20, 2011
 * @author HYE IN KIM
 * @version Spring 2011 v1.0, University of Washington
 */
(Empty line)
(Empty line)
Package statement;
Any import statements;
(Empty line)
(Empty line)
/**
 * Description about the class
 */
public class ClassName extends SomeClass implements Interface1, Interface2 {
	private static type STATIC_FIELD_NAME = ...;                // Field comment
	private final type CLASS_CONSTANT_NAME = ...;         // Field comment
	private type classFieldName;                                             // Field comment
(Empty line)
(Empty line)
	/*
	 * Constructor comment
	 */
	public ClassName(...) {
		Most important constructor that does most of the work
		Initialize all non-static fields
	}
(Empty line)
	/*
	 * Other constructors, less important
	 */
	public ClassName(...) {
		this(...);
	}
(Empty line)
	// Any private method that is used by constructor
	private returnType somePrivateMethod() {
	}
(Empty line)
(Empty line)
        /*
	 * Important static method1
	 */
	public static returnType aStaticMethod1(...) {
		Parameter checking code1;
                Parameter checking code2;
(Empty line)
                if(test1 && test2) {           // Any in-line comments
                	...                    // lines up within a method
                } else if(test3) {             // so that it is easy to spot & read
                	...
                } else {
                	...
                }
	}
(Empty line)
        /*
	 * Important static method2
	 */
	public static returnType aStaticMethod2(...) {
		// Some short statements like try catch that doesn’t do much
 		// (things like closing a scanner) can be written in one line.
		try{ oneLine short statement; }catch (Exception e){ short statement; }
		if(test) { short unimportant statement; }else{ short unimportant statement; }
	}
(Empty line)
	// Any private method that is used by static methods
	private returnType somePrivateMethod() {
	}
(Empty line)
(Empty line)
        /*
	 * Important setter1 (mutator): Changes state of the class
	 */
	public returnType setSomething1(...) {
	}
(Empty line)
        /*
	 * Important setter2 (mutator): Changes state of the class
	 */
	public returnType setSomething1(...) {
	}
(Empty line)
	// Any private method that is used by mutators
	private returnType somePrivateMethod() {
	}
(Empty line)
(Empty line)
        /*
	 * Important getter1 (accessor): Returns information about class’s state
	 */
	public returnType getSomething1(...) {
	}
(Empty line)
        /*
	 * Important getter2 (accessor): Returns information about class’s state
	 */
	public returnType getSomething1(...) {
	}
(Empty line)
	// Any private method that is used by assessors
	private returnType somePrivateMethod() {
	}
(Empty line)
(Empty line)
        /*
	 * Methods for convenience, not core functionality for the class
	 */
	public returnType equals(...) {
	}
(Empty line)
        /*
	 * Methods for convenience, not core functionality for the class
	 */
	public returnType clone(...) {
	}
(Empty line)
        /*
	 * Methods for convenience, not core functionality for the class
	 */
	public returnType toString(...) {
	}
(Empty line)
(Empty line)
(Empty line)
	/*
	 * Any Inner class
	 */
	private class AnInnerClass {
		Same convention as outer class
	}
}
-------------------------------------------------------------------------------------------------------