CSC 509 Design and Implementation Conventions
for Java Programs
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 functions it
* provides. The function descriptions in this header comment are generally
* brief, e.g., "Class X provides functions to add, delete, change, and find
* its elements." Do not list all of the function details in the header
* comment, since full comments for each function appear below in the body of
* the class, at the cite of each function 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
* member function implementation.
*
*
* Author: Full name and current email address of file's author; name is at
* least first and last, with middle name or initial if necessary or
* commonly used by author; email address appears in parentheses
* following full name; email address may be abbreviated to a local
* address if the full address can be expected to be known to. E.g.,
* Gene Fisher (gfisher@thyme); John H. Smith (john_smith).
*
* Create Date: Date file was originally created (NOT last modified), in the
* format ddmmmyy, where dd is a one or two-digit month date, mmm
* is the three-character all lowercase abbreviation for the
* month, consisting of the first three characters of the month
* name, yy is a two-digit year. E.g., 31jan00.
*
*/
[public] class X : extends Y implements Z {
/**
* Prose description of the function, describing what the function 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
* member used as an input and each data member modified as an output.
* Modification to a parameter or data member includes indirect
* modification to the value of a reference parameter or data member.
* Stylistically, use complete sentences, avoid passive voice.
*
* pre: formal precondition
*
* post: formal postcondition
*
*/
public T1 FuncName(T2 t2, ..., Tn tn) [throws ...] {
/*
* Include comments for each local variable and comments above each
* line or group of lines that describe how the function 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 function body.
*/
}
... other public functions ...
Note no public data members
Protected functions in same format as public functions.
/** Comment describing data member */
protected T1 varname;
... other protected data members ...
};
T1 FuncName(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;
}
}
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);}
}