CSC 309 Standard Operating Procedures, Volume 2:
Java Design and Implementation Conventions
import ... ;
/****
*
* The comment at the top of a .java file is a high-level description of the
* class defined in the file. Start the description with the words "Class X"
* and then describe the purpose of the class and the major methods it
* provides. The method descriptions in this header comment are generally
* brief, e.g., "Class X provides methods to add, delete, change, and find
* its elements." Do not list all of the method details in the header
* comment, since full comments for each method appear below in the body of
* the class, at the site of each method declaration. The header comment can
* describe the data representation used in the class in high-level terms if
* it's germane to explaining what the class is for. The header comment does
* not describe low-level details of the data representation or any details of
* method implementation.
*
*
* @author Name and current email address of file's author(s); name is at
* least first and last, with middle name or initial if necessary or
* commonly used by author(s); email address appears in parentheses
* following full name; multiple authors are comma-separated. E.g.,
* Gene Fisher (gfisher@calpoly.edu), John H. Smith (john_smith@
* csun.edu).
*
*/
[public] class X extends Y implements Z {
/**
* Prose description of the method, describing what the method does,
* not how it is implemented. Describe the use of each parameter by name,
* refer to the instance object as "this", and use the word "return" to
* describe the return value if there is one. Also describe each data
* field used as an input and each data field modified as an output.
* Modification to a parameter or data field includes indirect
* modification to the value of a reference parameter or data field.
* Stylistically, use complete sentences, avoid passive voice.
*
* pre: formal precondition
*
* post: formal postcondition
*
*/
public T1 methodName(T2 t2, ..., Tn tn) [throws ...] {
/*
* Include comments for each local variable and comments above each
* line or group of lines that describe how the method works. All
* but the "totally obvious" lines of code should be commented.
* Comments for variables should be descriptive noun phrases. Comments
* for code lines should be in complete sentences.
*
* All code comments should be formatted exactly as as this one is: (1)
* start with "/*" on a separate line, indented to the current level of
* code indentation; (2) start each comment line with "*", indented to
* current indentation + 1; (3) end with "*/" on a separate line,
* indented to current indentation + 1.
*
* See below under "indentation and spacing conventions" for further
* discussion of the format of code within a method body.
*/
}
... other public methods ...
Note no public or private data fields
Protected methods in same format as public methods.
/** Comment describing data field */
protected T1 varname;
... other protected data fields ...
};
T1 methodName(T2 t2, ..., Tn tn) {
/* Comment ... */
Tv1 tv1;
...
/** Comment ... */
Tvm tvm;
/*
* Comment ... .
*/
for (...) {
/*
* Comment ... .
*/
if (...) {
...
}
/*
* Comment, if necessary.
*/
else if {
...
}
...
/*
* Comment, if necessary.
*/
else {
...
}
}
/*
* Comment ... .
*/
while (...) {
...
}
/*
* Comment ... .
*/
for (start-expression; while-expression; end-expression) {
...
}
/*
* Comment ... .
*/
for (long-start-expression ... ;
long-while-expression ... ;
long-end-expression) {
...
}
/*
* Comment ... .
*/
switch (...) {
/*
* Comment, if necessary.
*/
case c1:
...
break;
...
/*
* Comment, if necessary.
*/
case ck:
...
break;
}
}
In the preceding commenting convention, the '//' style of comments can be used
instead of the '/* ... */', but the two styles cannot be mixed. For multi-line
comments with '//', format as follows:
// // Comment ... //
boolean status int counter
for (i=1; i<=n; i++) {
if (i % 2) {
x.Foo1(i);
x.Foo2(i);
}
}
for (i=1; i<=n; i++) { if (i % 2) { x.Foo1(i); x.Foo2(i); } }
for (i=1; i<=n; i++) {
if (i % 2) {
x.Foo1(i);
x.Foo2(i);}
}