Program Style Guide |
Version
2.0.6 |
1. Naming |
1.1 Use meaningful names.
Use descriptive names for all identifiers
(names of classes, variables and methods).
Avoid ambiguity. Avoid abbreviations.
Simple mutator methods should be named
setSomething(...).
Simple accessor methods should be named
getSomething(...).
Accessor methods with boolean return values are often called
isSomething(...),
for example, isEmpty().
1.2 Class names start with a capital letter.
1.3 Class names are singular nouns.
Plural is meaningful : for example, an Item class
should contain a single item, and an Items
class should be able to contain several of them.
1.4 Method and variable names start with lowercase
letters.
All three - class, method and variable names
- use capital letters in the middle to increase readability
of compound identifiers, e.g. numberOfItems.
1.5 Constants are written in UPPERCASE.
Constants occasionally use underscores to
indicate compound identifiers: MAXIMUM_SIZE
1.6 static member names (fields and methods) start with a lowercase s,
except for constants.
1.7 Other variable names start with a specific letter describing their role :
- attributes (fields) start with a lowercase a
- parameters start with a lowercase p
- local variables start with a lowercase v
|
2. Layout |
2.1 One level of indentation is four spaces.
2.2 All statements within a block are indented
one level.
2.3 Braces for classes and methods are alone
on one line.
The braces for class and method blocks are
on separate lines and are at the same indentation level,
for example:
public class Circle
{
1. attributes
2. constructors
3. methods
}
|
|
public void procedure()
{
statements
}
|
2.4 For all other blocks, braces open at the
end of a line.
All other blocks open with braces at the end
of the line that contains the keyword defining the block.
The closing brace is on a separate line, aligned under the
keyword that defines the block.
For example:
while (condition) {
statements
}
|
|
for (
initialization;
condition;
progression ) {
statements
}
|
if (condition1) {
statements
}
else if (condition2) {
statements
}
else {
statements
}
|
|
switch (expression) {
case value1 :
statements
break;
case value2 :
case value3 :
statements
break;
default :
statements
}
|
2.5 Always use braces in control structures.
Braces are used in if-statements and loops
even if the body is only a single statement,
except for single-line if-statements and loops, for example :
if (n<2) return 0;
|
|
for (int i=0; i<tab.length; i++) tab[i]=i;
|
2.6 Use a space
after a keyword, and
before the opening brace of
a control structure's block.
2.7 Use a space
around operators
and after each comma in a list of parameters.
2.8 Use a blank line between methods (and constructors).
Use blank lines to separate logical blocks of code. This
means at least between methods, but also between logical
parts within a method.
|
3. Documentation |
3.1 Every class has a class comment at the
top.
The class comment contains at least
- a general description of the class
- the author's name(s)
- a version number
Every person who has contributed to the class
has to be named as an author or has to be otherwise appropriately
credited.
A version number can be a simple number, a
date, or other formats. The important thing is that a reader
must be able to recognise if two version are not the same,
and be able to determine which one is newer.
3.2 Every method has a method comment.
3.3 Comments are Javadoc-readable.
Class and method comments must be recognised
by Javadoc. In other words: they should start with the comment
symbol /**.
And javadoc comment tags @param, @return, and @throws
should be used (if appropriate) in each method comment.
3.4 Code comments (only) where necessary.
Comments in the code should be included where
the code is not obvious or difficult to understand (while
preference should be given to make the code obvious or easy
to understand where possible), and where it helps understanding
of a method. Do not comment obvious statements - assume
your reader understands Java!
In particular, every closing brace } should be commented to explain
which block it is closing. For example :
// OneClass for the class, or
// OneClass(..) for the constructor with two parameters, or
// else for an if/else instruction.
3.5 To be able to comment some interesting fields,
always declare each field on its own line.
|
4. Language use restrictions |
4.1 Order of declarations: fields, constructors, methods.
The elements of a class definition appear (if present)
in the following order:
package statement; import statements;
class comment; class header; field definitions; constructors;
methods.
4.2 Fields may not be public
are always private
(except for final fields),
even in super-class.
4.3 Always use an access modifier.
Specify all fields and methods as either
private, public, or protected.
Never use default (package private) access.
4.4 Import classes separately.
Import statements explicitly naming every class are preferred
over importing whole packages. E.g.
import java.util.ArrayList;
import java.util.HashSet;
is better than
import java.util.*;
and classes from the same package must be listed in alphabetical order.
4.5 Always include a constructor (even if the body is empty),
except for classes without any field
.
4.6 Always include superclass constructor call.
In constructors of subclasses, do not rely on automatic
insertion of a superclass call. Include the super(...); call
explicitly, even if it would work without it.
4.7 Initialise all fields in the constructor
(even if you put default values).
4.8 Always use this. when possible.
For example :
this.aField = 0;
this.setField(0);
is better than
aField = 0;
setField(0);
4.9 Use final in front of each parameter declaration.
4.10 Use @Override each time you want to redefine a method.
In fact, use it each time you write a signature which already exists
in a super class or a currently implemented interface.
|
5. Code idioms |
5.1 Use iterators with collections.
To iterate over a collection, use a for-each loop
(each time it's possible).
When the collection must be changed during iteration use
an Iterator, not an integer index.
5.2 Use if/else instead of two ifs.
For example :
if ( a == 2 ) { statements1 }
else { statements2 }
is better than
if ( a == 2 ) { statements1 }
if ( a != 2 ) { statements2 }
|
Copyright notice
Copyright
(c) Michael Kölling and David Barnes,
completed by Denis Bureau
(ESIEE).
Above advices written in orange are optional.
[Denis Bureau]
This style guide was written for the book
Objects First With Java - A Practical Introduction Using
BlueJ.
Permission is granted to everyone to copy,
modify and distribute this document or derived documents in
any way. We would appreciate a reference to the original source
in derived documents.
|
|