This page describes the style in which you are to program for this class. Although 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.
Note that the code provided to you for some of the labs nearly conforms to this guide. First, you should follow the guide before following such 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 classes (where appropriate), where each class provides a distinct set of capabilities that can be used by another class.
Each class should be well encapsulated, and thus portable to code other than your own. Avoid circular dependencies: If class A depends on class B, then B should not also depend on A if at all avoidable.
The code for each class, no matter its size, should be wholly contained in a single file.
Within a class, divide and encapsulate your code thoroughly with methods. If a common task can easily be extracted into another method, then do so.
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 method. Another example of a segment is the data members for the class. Yet another example is a segment that contains all of the import commands at the head of a file.
Each segment of the code should be surrounded by divider comment lines -- those comment lines that contain only a sequence of dash (-) characters to visually separate the segments.
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.
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 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 it is absolutely unavoidable. (Note that XEmacs wrapping occurs at 72 characters. Use M-x column-number-mode to see the width of your lines, and M-x auto-fill-mode to have XEmacs automatically wrap your lines. You can also use M-q to force XEmacs to immediately wrap the line/paragraph on which the cursor is currently sitting. If that goes badly, C-/ is the undo function.)
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 XEmacs indentation must be used.
Names must by default be descriptive and must not be abbreviated. (It 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.
Data member names must include an underscore (_) as a prefix. This rule helps to easily identify the use of data members (versus local variable or parameters) within a method.
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:
Each group of lines of code should be commented, even if the task being performed by those lines is simple.
Each method should be preceeded by a comment that describes that 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 be placed on lines that preceed the code to which they refer.
All elements of your code must be commented, including the declaration and assigning of constants and import statements.
The segments should follow a consistent sequence:
When defining a method: