CS 1704 - Summer II 2003

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.

• 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.

• 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.

• 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.