|
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 will be used. 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 ( 4 + 6 / 2 )
- between
control structures and their conditionals ( if ( a ) { )
- 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 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 be in all lower case.
- 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 mixed 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 are allowed 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 effectively and should be redesigned.
I mean comments that share a line with executable code. In general,
I also discourage comments within the executable block, but I go back
and forth on this. In general, if in- block comments are used, I request
that they be blocked off the same as banner comments, to maintain continuity.
Obviously this is a personal quirk.
- 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 comment in or out of the code doesn't
produce a compilation error.
- All
comments should use the entire line width and shall 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 section.
- The
sections should line up vertically.
- The
section identifiers should be capitalized.
- 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 declared/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,
or 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 approp *
// *
// LOGIC: Specific logic required to implement the *
// algorithm, when appropriate. *
// *
// IMPLEMENT DETAILS: Issues in implementing the alg *
// *
// 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 *
// *
// VARIABLES: int n - loop counter *
// arrayType a - the array to sort *
// *
//*****************************************************
#include <stdlib.h> //- for rand
#include <iostream.h> //- standard I/O
#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;
}
|
|
|
|
|
