This page describes the style in which you are to program for this class. While you may have your own chosen style for programming, it is important that you follow this guide as closely as possible. Note that any guide, including this one, will leave latitude for personal choices. In making those choices, be consistent. It is critically important that you code be easy to read and understand for another programmer. Clarity and consistency of presentation are critical, and require real work to achieve. This guide should be useful for ensuring a consistency to presentation.
Since this is the first version of this style guide, it may contain typos, inconsistencies, unspecified elements, or other errors. Please communicate any problems that you identify to me so that I can correct, expand, and otherwise modify this document.
This style guide will rely heavily on sample code:
These samples nearly conform to this guide. First, you should follow the guide before following the samples. Second, there is slight latitude for deviating from the guide. If you do deviate, you must do so consistently, you should provide a good reason, and I recommending not doing so any more than the samples do.
Divide your code into modules, where each module provides a distinct set of capabilities that can be used by another module.
Each module should be well encapsulated, and thus portable to code other than your own. Avoid circular dependencies: If module A depends on module B, then B should not also depend on A if at all avoidable.
If you are using object orientation, there must be a one-to-one correspondence between classes and modules.
Within a module, divide and encapsulate your code thoroughly with functions/methods. If a common task can easily be extracted into another function/method, then do so.
There must be a main module that contains only the main() function. That main() function should return int, not void. The return value should be 0 for any normal execution.
Every module other than the main module must comprise both a head and a code file (see below).
Use a Makefile to automatic the compilation and linking of your code. You must use the -Wall compilation to generate all compiler warnings. (Your finished code should have none.)
You code should be accompanied by a README file that explains how to compile the code, how to run the resulting executable, and what limitations may exist for using the executable. Your writing must be well structured and use correct English.
Your code should be divided into segments, where each segment is a sequence of lines that serve a similar purpose. One example of a segment is a single function or method. Another example of a segment is the set of #include directives.
Each segment of the code should be surrounded by divider comment lines -- those comment lines that contain only a sequence of dash (-) characters.
The segments should follow the sequence given below for header and for code files.
There should exactly three (3) blank lines between each segment.
Within the body of a function, method, structure, or class definition, tightly associated lines should be grouped together, with no blank lines inbetween. There should be exactly one (1) blank line between these tightly associated groups of lines.
There must be a space on either side of any operator (that is, +, -, ==, etc.).
Declare only one variable per line.
When declaring a pointer, the asterisk (*) must immediately follow the type that it modifies (no spaces inbetween). There must be a space following the asterisk, before the variable name is given.
No space should separate a type cast from the variable or expression that it modifies.
For control structures (e.g. if, for, while, etc.), a space should separate the keyword from the parenthesized conditional expression. A space should then separate that conditional expression from opening and closing braces ({, }).
All control structure bodies must be enclosed in braces, even if the body comprises only a single statement. A blank line must separate each brace from its enclosed statements.
Enclosing braces must not be on the same line as a statement contained by those braces.
A function/method call should not have a space separating the name from the parenthesized argument list.
No line of code should be longer than 72 characters unless absolutely unavoidable. (Note that (X)Emacs wrapping occurs at 72 characters. Use M-x column-number-mode to see the width of your lines.)
Parameter and argument lists with more than one element should have no space before each comma, and one space after each comma.
If a parameter or argument list does not fit on a single, 72-character line, then it should be divided into multiple lines where exactly one (1) parameter/argument appears per line.
Expressions that do not fit on a single, 72-character line should be divided into multiple lines such that:
Avoid complex, compound expressions. Name local variables to store partial results from subexpressions, and then use those local variables in the larger expression, thus separating complex expression into multiple lines.
The default (X)Emacs indentation must be used.
Names must by default be descriptive and must not be abbreviated. (Itt is often difficult to select names, and it should be, given that you are trying to encapsulate substantial meaning such a short representation.) The following exceptions may be applied to this rule:
Class names must be capitalized. No other names may be capitalized.
Type names must include the suffix _t.
Structure names must include the suffix _s.
When using object orientation, data member names must include an underscore (_) as a prefix.
Names composed of multiple words should combine those words in one the two following formats. Do not mix these two formats -- select one and use it everywhere:
Do not use the C-style (/* */) comment delimiters. Use only the C++-style (//) comment leader.
Each group of lines of code should be commented, even if the task being performed by those lines is simple.
Each function/method should be preceeded by a comment that describes that function/method.
Comments should be descriptive and written in proper English. When a short phrase, rather than a whole sentence, can clearly communicate the purpose of the comment, then you may use that short phrase.
Comments must always be placed on lines that preceed the code to which they refer.
All elements of your code must be commented, including constants and #include statements.
Each header file must contain the following segments in the following order:
Multiple inclusion must be avoided using pre-processor directives. The beginning and ending segment of each header file should follow exactly the formatting and naming convention showed in example header file.
The parameter lists of function and method prototypes (that is, the declared function/method without its body) must indicate not only types but also names.
For class definitions, the public paragraph must be presented first, and private or protected paragraphs later.
All function and method prototypes must be throughly commented, forming a kind of documentation for the use of that module.
Each code file must contain the following segments in the following order:
When defining a function or method:
Functions and methods should be ordered from lowest to highest level. That is, the most high-level functions/methods that call other functions/methods in the module should be last. The lowest-level functions/methods that do not call others in the module should be first.