CSE 308. Coding Conventions. Reference

(1)

CSE 308

Coding Conventions

Reference

TJava Coding Conventions

google-

styleguide.googlecode.com/svn/trunk/javaguide .html

TJava Naming Conventions

www.ibm.com/developerworks/library/ws-tip- namingconv.html

(2)

© Robert Kelly, 2005-2015 3

Why Do We Need Coding Conventions?

T Reduce software maintenance T Improve readability of the SW

SEasier code walkthroughs and design reviews

Comments

T Comments will be

S Implementation - /* … */

S Javadoc - /** … */

T Implementation comments are for commenting out code or describing particular implementation issues

T Comments should provide only info that is not available in the code (don’t document trivial issues)

T Don’t use special characters, boxes, etc.

(3)

© Robert Kelly, 2005-2015 5

Appearance

T Indentation

S2 spaces is recommended (4 is OK)

SUse the formatting feature of your IDE (tailor your settings)

Helpful to use the IDE format feature regularly as

you are coding – it helps you see errors

Line Wraps

T Rules:

SBreak after a ,

SBreak before an operator

SLine wrapping – indent at least 4 spaces

X = a +b;

(4)

© Robert Kelly, 2005-2015 7

Class Statement Organization

T Static variables – in the order of:

Spublic Sprotected Sprivate

T Instance variables (same order as static variables) T Constructors

T Methods – group by functionality (make reading code easier)

Declarations …

T Declarations at the beginning of a block T One declaration per line

T You can either use a space or a tab between the type and the identifier

Sint level //authorization level Sint level //authorization level

(5)

… Declarations

T Some logical ordering T No C++ array declarations

© Robert Kelly, 2005-2015 9

String[] args, not String args[]

Annotations

T Annotations applying to a class, method or constructor appear immediately after the documentation block

T Each annotation is listed on a line of its own (that is, one annotation per line)

T These line breaks do not constitute line-wrapping

@Override

@Nullable

public String getNameIfPresent() { ... }

(6)

© Robert Kelly, 2005-2015 11

Statements

T One statement per line

T Return statements should not use ()

return myObject;

If statements

T Examples

if (condition) { statements }

if (condition) { statements } else {

statements

Always use {} in your if statements

(7)

© Robert Kelly, 2005-2015 13

Iteration statements

T Examples

while (condition) { statements }

do {

statements } while (condition);

Always use {} in your iteration

statements

for (initialization, condition, update) { statements

}

Blank Lines

T Between methods

T Between local variables in a method and the first statement

T Between logical sections

Beware of using too many blank lines – remember your module should be readable on a screen

(8)

© Robert Kelly, 2005-2015 15

Naming Conventions

T Packages – lower case (not CC)

T Classes – should be nouns in upper camel case

SFirst letter of each internal word is capitalized

SUse whole words – avoid acronyms and abbreviations

T Methods – should be verbs in lower camel case T Variables –

lower camel case

SDon’t use _ or $

T Constants – all uppercase

Ambler Name Suggestions

T Use full descriptors (e.g., firstName) T Use domain terminology

T Use abbreviations sparingly

T Avoid long names (e.g., 15 character max) T Avoid names that are too similar

(9)

Worthless Documentation

/**

* Represents a command history

*/

public class CommandHistory { /**

* Get the command history for a given user

*/

public static CommandHistory

getCommandHistory(String user) { }

}

Javadoc

T Theme: Include your code documentation in the code – and then extract it to an html file

T Principles

S Javadoc comments are a special form of java comments S Classes, methods, and fields are documented – immediately

above the feature it documents

S Comments include tags (starting with a @), such as @author and @param

S Comments can include html tags, such as <code>, <em>, and

<br>

T Javadoc output (html) is generated by your IDE or by a command

Javadoc will not be evaluated

(10)

Block Tags

T Include block tags in the following order:

S @param (classes, interfaces, methods and constructors only) S @return (methods only)

S @exception (@throws is a synonym added in Javadoc 1.2) S @author (classes and interfaces only, required)

S @version (classes and interfaces only, required.

S @see S @since

S @serial (or @serialField or @serialData)

Structure

T One class per file