| |
Basic
Style and Documentation Guidelines
Style
- All source code should be submitted in constant-width
fonts, no bold or italics, (10 point courier or equivalent).
- No tab stops should be used in any source
code submissions. If used on the original, conversion to spaces
should be done for submission. Tab stops vary with editor,
and cannot be guaranteed when transferred from one machine
to another. Projects are graded partly on documentation and
style, so consistency is important.
- Functional indentation should be used in
all control structures. Indentation stops should be consistent
and should be 3 or 4 horizontal spaces.
- Horizontal spacing should be used for clarity
of readability:
- between operators and operands (e.g.,
4 + 6 / 2 )
- between control structures and their
conditionals (e.g.,
if ( a ) { )
- between arguments (i.e., after commas)
- to line up arguments, as in declarations,
assignments, multi-line logical expressions
- between control structure headers and
their expressions (this is indentation, use the same indentation
amount consistently)
- Function/Method prototypes should appear
on one line. Parameter overflow should be lined up under the
first parameter.
- Function/Method definition should appear
on two lines, the declaration type on the first line and the
identifier and parameter lists on the next line. Overflow
should be lined up under the opening parenthesis.
- Vertical spacing should be used for readability
and clarity:
- between documentation banners and function
headers (1 line).
- between statement blocks of different
types (e.g., declarations and assignments, includes and
defines, I/O statements and other statements, control
structures and other statements)
- between compound statement curly braces
and other statements (line feed only)
- between executable code and function/method
return statements, for clarity
- All functions/methods (except constructors/destructors)
should have type declarations and return types (even if void).
This is for consistency.
- All functions/methods should have parameter
lists (even if void). This is for consistency.
- All variables should begin with lower case
characters.
- All constants and enumerations should be
in all upper case.
- All types should be begin in lower case and
then move to mixed case.
- All function/method identifiers should be
in full mixed case (i.e., each word will begin with a capital
and the rest of the word will be lower case).
- Curly braces should only be used for compound
statements. They should not be used in )switch) statements.
They should not be used in other control structures (except
functions/methods, particularly stubs) when there is only
one executable line of code for the control structure.
- There should only be a single executable
expression per line. No executable expressions should be on
the same line as a control structure header (e.g.,
while
( foo ) { a = b; } is not good style).
Documentation
- All documentation should be placed in banners
ABOVE the related code fragment. No comments should be in
in-line in submissions. In-line comments are for debugging.
Code that is so long that comments are needed to break it
up has not used abstraction e ffectively and should be redesigned.
-
'In-line' comments means comments
that share a line with executable code. In general, the use
of comments within an executable block of code is discouraged
because of the above reason. In general, if in-block comments
are used, they should be blocked off the same way as banner
comments, to maintain continuity.
-
All comments should be self-terminating.
There should be no run-on comments. Each comment should start
and end on a single line, so that editing a line in or out
of the comment doesn't produce a compilation error.
-
All comments should use the
entire 'line' width (as defined by whatever width you use
for your banner) and should be bounded by characters that
clearly identify them as comments.
-
All comments should be separated
from code by one blank line on both sides.
-
Contents of banners:
- Banners should be organized by functional
section.
- The sections should line up vertically.
- The section identifiers should be
capitalized to set them apart.
- Sections should be separated by vertical
space for readability.
- The contents of sections should line
up vertically.
- Types and identifiers should line
up, separators (such as hyphens) should line up and
descriptions should line up. This is all for readability
clarity.
- When algorithm flow, figures, compilation
sequences, etc. are included, they should be indented
so as to set them apart from the rest of the section.
- When a line or a list of items do not
allow for effective lining up, then the section header
should be separated from the contents by a blank line.
- Headers/Interfaces Section Identifiers
(example template):
//********************************************************
// FILE: As it is in the current directory *
// *
// AUTHOR: Whomever + citations *
// *
// USAGE COMMENTS: On compilation, usage, etc. *
// *
// LIBRARIES: Included libraries and why *
// *
// TYPES DEFINED: All typedefs, enumerations, classes *
// *
// CONSTANTS DEFINED: *
// *
// FUNCTIONS/METHODS DECLARED: *
// *
// void Myfun1 -- Description of MyFun1 *
// int Myfun2 -- Description of MyFun2 *
// Boolean Myfun3 -- Description of MyFun3, this one *
// carries over to another line *
// void Myfun4 -- Description of MyFun4 *
// myClass Myfun5 -- Description of MyFun5 *
// *
// GLOBAL VARIABLES USED: *
// *
// GENERAL COMMENTS: *
// *
//********************************************************
- Implementation Section Identifiers (example
template):
-
The banner for the main
block, or for libraries, should have the same kinds of
information as for the interface, but the types, constants,
and globals should be missing, and there may be variable
definitions in the case of a main block. If functions
are d eclared/defined locally, then they should be in
a separate header.
//********************************************************
// FILE: As it is in the current directory *
// *
// AUTHOR: Whomever + citations *
// *
// USAGE COMMENTS: On compilation, usage, etc. *
// *
// LIBRARIES: Included libraries and why *
// *
// FUNCTIONS/METHODS DEFINED: *
// *
// void Myfun1 -- Description of MyFun1 *
// int Myfun2 -- Description of MyFun2 *
// Boolean Myfun3 -- Description of MyFun3, this one *
// carries over to another line *
// void Myfun4 -- Description of MyFun4 *
// myClass Myfun5 -- Description of MyFun5 *
// *
// VARIABLES DEFINED: In main *
// *
// GENERAL COMMENTS: *
// *
//********************************************************
-
Function/Method Prototypes
(example template):
Documentation for function
prototypes, being an interface only need to tell the reader
what the function expects and what they can expect from
the function. The header will tell them the parameter
types and their order, as well as the function return
type , but these can also be included in the documentation
for clarity.
//********************************************************
// IDENTIFER: FUNCTION Of Function/Method *
// *
// PRE: Precondition of the function/method *
// *
// INPUT: Description of input parameters *
// *
// OUTPUT: Descriptions of output parameters *
// *
// POST: Postcondition of the method *
// *
// INVARIANT: Invariant of the method *
// *
// RETURN: Value returned by the function/method *
// *
//********************************************************
-
Function/Method Definitions
(example template):
Functions require the most
in-depth documentation, as they are *live: documentation
for any programmer to use while development is ongoing,
of if they ever revisit the code, or if any other programmer
ever reads the code.
//********************************************************
// IDENTIFER: FUNCTION OF FUNCTION/METHOD *
// *
// PRE: Precondition of the function/method *
// *
// INPUT: Description of input parameters *
// *
// LOCAL: Descriptions of important local variables *
// *
// OUTPUT: Descriptions of output parameters *
// *
// POST: Postcondition of the method *
// *
// INVARIANT: Invariant of the method *
// *
// ALGORITHM: Method for achieving function, when *
// appropriate. *
// *
// LOGIC: Specific logic required to implement the *
// algorithm, when appropriate. *
// *
// IMPLEMENTATION DETAILS: Issues in implementing the *
// algorithm, when appropriate. *
// *
// CALLS: Methods/functions this function calls *
// *
// RETURN: Value returned by the function/method *
// *
// COMMENTS: General *
// *
//********************************************************
-
EXAMPLE: BUBBLE SORT
//*****************************************************
// FILE: BubbleSort.C: Driver that sorts the items *
// in an array into ascending *
// order. *
// *
// AUTHOR: Frank Carrano, Chapter 9, pp 410-411 *
// *
// LIBRARIES: - for rand *
// - standard I/O *
// *
// VARIABLES: int n - loop counter *
// arrayType a - the array to sort *
// *
//*****************************************************
#include
#include
#define MAXSZ 12
typedef int dataType;
typedef dataType arrayType[MAXSZ];
void BubbleSort(dataType a[MAXSZ]);
void Swap(dataType& x, dataType& y);
int
main(void)
{
arrayType a;
int n;
for ( n = 0; n < MAXSZ; n++ )
a[n] = rand();
cout << "The array before sorting is:\n\n";
for ( n = 0; n < MAXSZ; n++ )
cout << a[n] << endl;
cout << endl;
BubbleSort(a);
cout << "The array after sorting is:\n\n";
for ( n = 0; n < MAXSZ; n++ )
cout << a[n] << endl;
cout << endl;
return(0);
}
//*****************************************************
// BubbleSort.C: Sorts the items in an array into *
// ascending order. *
// *
// PRE: )a) is an array of MAXSZ items *
// POST: )a) is sorted into ascending order *
// *
// TYPES: enum boolean {FALSE, TRUE} *
// *
// VARIABLES: boolean sorted - logical result *
// int pass - current outer loop *
// int index - lower comparison *
// index *
// int nextIndex - upper comparison *
// index *
// *
// APPROACH: *
// *
// Initially, the sorted regions is a[0] and the *
// unsorted region is a[sorted..n - 1]. In *
// general, the sorted region is a[0..unsorted - 1] *
// and the unsorted region is a[unsorted..n - 1] *
// *
// OLOOP INVARIANT: a[n + 1 - pass..n - 1] is sorted *
// and > a[0..n - pass] *
// *
// ILOOP INVARIANT: a[0..index - 1] <= a[index] *
// *
// CALLS: Swap *
// *
//*****************************************************
void
BubbleSort(dataType a[MAXSZ])
{
enum boolean {FALSE, TRUE};
boolean sorted = FALSE;
int pass, index, nextIndex;
for ( pass = 1; (pass < MAXSZ) && !sorted; pass++ ) {
sorted = TRUE;
for ( index = 0; index < MAXSZ - pass; index++ ) {
nextIndex = index + 1;
if ( a[index] > a[nextIndex] ) {
Swap(a[index], a[nextIndex]);
sorted = FALSE;
}
}
}
return;
}
//***********************************************************
// Swap: Swaps x and y *
// *
// PRE: None. *
// INPUT: dataType& x, y -- data to exchange *
// LOCAL: dataType temp -- temporary data *
// OUTPUT: dataType& x, y -- swapped data *
// POST: Contents of actual locations that x and y *
// represent are swapped. *
// *
//***********************************************************
void
Swap(dataType& x, dataType& y)
{
dataType temp;
temp = x;
x = y;
y = temp;
return;
}
|
| |
|