Design and Implementation Conventions
in the C+- Subset of C++
6th DRAFT
28 January 2011
////
//
// The comment at the top of a .h file is a high-level description of the class
// defined in the file. Start the description with the words "Class XXX" and
// then describe the purpose of the class and the major functions it provides.
// The function descriptions in this header comment are generally brief, e.g.,
// "Class XXX provides functions to add, delete, change, and find its
// elements." Do not list all of the function details in the header comment,
// since full comments for each function appear below in the body of the class,
// at the cite of each function declaration. The header comment can describe
// the data representation used in the class in high-level terms if it's
// germane to explaining what the class is for. The header comment does not
// describe low-level details of the data representation or any details of
// member function implementation.
//
//
// Author: Full name and current email address of file's author; name is at
// least first and last, with middle name or initial if necessary or
// commonly used by author; email address appears in parentheses
// following full name; email address may be abbreviated to a local
// address if the full address can be expected to be known to. E.g.,
// Gene Fisher (gfisher@calpoly.edu); John H. Smith (john_smith@...).
//
// Create Date: Date file was originally created (NOT last modified), in the
// format ddmmmyy, where dd is a one or two-digit month date, mmm
// is the three-character all lowercase abbreviation for the
// month, consisting of the first three characters of the month
// name, yy is a two-digit year. E.g., 31jan98.
//
////
#ifndef xxxIncluded
#define xxxIncluded
#include ...
class X : public Y {
public:
T1 FuncName(T2 t2, ..., Tn tn);
//
// Prose description of the function, describing what the function does,
// not how it is implemented. Describe the use of each parameter by name,
// refer to the instance object as "this", and use the word "return" to
// describe the return value if there is one. Also describe each data
// member used as an input and each data member modified as an output.
// Modification to a parameter or data member include indirect modification
// to the value of reference or pointer-valued parameter or data member.
// Stylistically, use complete sentences, avoid passive voice.
//
// pre: formal precondition
//
// post: formal postcondition
//
// catch: list of exception objects caught
//
// throw: list of objects thrown
//
... other public functions ...
Note no public data members
protected:
Protected functions in same format as public functions.
T1 varname; // Comment describing data member
... other protected data members ...
};
////
//
// Implementation of XXX.
//
////
T1 XXX::FuncName(2 t2, ..., Tn tn) {
Note that function signature is identical to that declared in .h file,
including spellings of parameter names
//
// Include comments for each local variable and comments above each line or
// group of lines that describe how the function works. All but the
// "totally obvious" lines of code should be commented. Comments for
// variables should be descriptive noun phrases. Comments for code lines
// should be in complete sentences.
//
// All code comments should be formatted exactly as as this one is: (1)
// start with "//" on a separate line, indented to the current level of
// code indentation; (2) start each comment line with "//", indented to
// current indentation + 1; (3) end with "//" on a separate line, indented
// to current indentation + 1.
//
}
See below under "indentation and spacing conventions" for further discussion of
the format of code within a function definition.
typedef int Coordinate
is conventionally correcttypedef String Name
is not correct.typedef String* Name
T1* FuncName(T2* t2, ..., Tn* tn) {
Tv1* tv1; // Comment ...
...
Tvm* tvm; // Comment ...
//
/ Comment ... .
//
for (...) {
//
// Comment ... .
//
if (...) {
...
}
//
// Comment, if necessary.
//
else if {
...
}
...
//
// Comment, if necessary.
//
else {
...
}
}
//
// Comment ... .
//
while (...) {
...
}
//
// Comment ... .
//
for (start-expression; while-expression; end-expression) {
...
}
//
// Comment ... .
//
for (long-start-expression ... ;
long-while-expression ... ;
long-end-expression) {
...
}
//
// Comment ... .
//
switch (...) {
//
// Comment, if necessary.
//
case c1:
...
break;
...
//
// Comment, if necessary.
//
case ck:
...
break;
}
bool status int counter
for (i=1; i<=n; i++) {
if (i % 2) {
Foo1(i);
Foo2(i);
}
}
for (i=1; i<=n; i++) { if (i % 2) { Foo1(i); Foo2(i); } }
for (i=1; i<=n; i++) {
if (i % 2) {
Foo1(i);
Foo2(i);}
}