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, or structs
with member functions, in solving
the programming assignments in CS 1044.
- You are explicitly forbidden to write classes, or structs
with member functions, in solving the programming assignments in CS 1704,
unless the assignment specification explicitly states otherwise.
- You are expected to use some of the C++ Standard Library
classes, including I/O streams and strings, as covered in the course notes.
AP Issues:
- The AP Computer Science courses typically use types that
are not sanctioned by the ISO/ANSI C++ Standard, including APstring
and APvector. The use of any such non-Standard types is expressly
banned. Standard C++ includes superior alternatives, which will be
introduced when they are appropriate.
Last modified: Saturday, August 31, 2002
Please send comments and suggestions to William McQuain at mcquain@cs.vt.edu.