CS 2606 General Programming Standards
Internal
Documentation Requirements:
- Each source and header 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 must be accompanied by a header 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.
- 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).
Procedural 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.
- Do not use global or file-scoped variables under any
circumstances. It IS permissible to use globally scoped type
definitions (including class declarations).
- Pass function parameters with appropriate access. Use
pass-by-reference or pass-by-pointer only when the called function needs to
modify the value of the actual parameter. Use
pass-by-constant-reference or pass-by-constant-pointer when passing large
structures that are not modified by the called function. Use
pass-by-value when the called function must modify the formal parameter
(internal to the call) but the actual parameter should remain unmodified.
- Store character data (aside from single characters) in
string objects, rather than char arrays.
- Use new-style C++ at all times; e.g., use <iostream>
instead of <iostream.h>. Do not
mix old and new style C++ headers.
- Use stream I/O instead of C-style I/O.
Object-Oriented Coding Requirements:
- Use classes where they are appropriate. Do not
implement struct types with member functions.
- When specified, use a template 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.
- If a class data member is a pointer to dynamically
allocated memory, implement a destructor to deallocate that memory.
- If a class data member is a pointer to dynamically
allocated memory, implement a deep copy constructor and assignment operator
overload.
- Use inheritance only when it makes sense to do so.
General
Restrictions:
- You may not use any STL containers (aside from
string) unless they are explicitly allowed by
the specification for an assignment.