CS 1044 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.
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:
-
You are explicitly forbidden to write classes in solving the programming
assignments in CS 1044.