Failure to follow these submission requirements will
result in assignment grade penalties! |
Internal Documentation Requirements
- Each source and package file must begin with a
comment block
identifying the programmer, project, and last modification date.
- The source file containing main()
must include a
comment block (following the identification header comment),
that briefly describes the purpose of the program and the primary data
structures employed.
- Each function/method must be accompanied by a
header
doc comment that
describes what the function does, the logical purpose of each parameter
(including whether it is input, output, or input/output), the pre-conditions
that a function call assumes and the post-conditions that are guaranteed,
the return value (if any), and a list of other functions called by this
function (if any). These function header comments may be placed with
the function prototype or with the function implementation.
-
Javadoc tags must be fully utilized.
- Declarations of all local variables and constants must be
accompanied by a brief description of purpose.
- Major control structures, such as loops or selections,
should be preceded by a block comment describing what the following code
does.
- Use a sensible, consistent pattern of indentation and other
formatting style (such as bracket placement) to improve the readability of
your code.
- Each class must have a header comment block that describes
the purpose of the class, at a reasonably high level. Class header
comments should be placed in immediately before the class declaration
(normally in a header file).
General Coding Requirements
- Identifier names (constants, variables, functions, classes,
etc.) should be descriptive.
- When a constant is appropriate, use a named constant
instead of a "magic number".
- Use enumerated types for internal labeling and
classification of state.
- When specified, use a formally generic class for container structures
such as lists, trees, etc.
- Design each class to have a coherent set of
responsibilities.
- Except for node classes used only with an encapsulating
class, all data members of a class should be private.
- In many cases, some of the member functions of a class
should also be private. Watch for that situation.
- Implement support for deep copy when it makes sense to do
so.
- Use inheritance only when it makes sense to do so.
General Restrictions
- You may NOT use any Java library containers unless they are explicitly allowed by
the specification for an assignment.
"Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing."
- Dick Brandon |