CS 141 - Coding Style Guide

CS 141 Coding Style Guide

Style is a vastly personal thing in "recreational" or "hobby" coding; however it is highly likely that you will be forced to adopt a specific coding style at some point in the future. (Perhaps because your employer has specific habits or you join an Open Source project with particular style guidelines.) Therefore, we will not be enforcing a specific style in this course, beyond a few general guidelines that are part of every "reasonable" style guide known to man.

Consistency: In much of the following we will present options for how to format your code. Where options are presented, we do not care which option your choose, SO LONG AS YOU ARE CONSISTENT. Consistency is the greatest virtue a coder can have with respect to style. Be consistent; it prevents situations where the reader believes you have some deep reason why you did strange thing X when in fact you were just being sloppy.

Indentation: Style debates rage over how far code should be indented per block of code. In this course we will accept any between 2 and 8, inclusive. (That is, 1 is not allowed, nor is 9, 10, etc.)
Note that your editor needs to interpret the TAB (\t) character as 8 spaces (note that in many editors, including EMACS, hitting TAB does not actually produce a TAB character, but rather a number of spaces). This is how we will be checking your code, and we are not responsible for any discrepancies in this regard.

Line Wraps: No program should have any line of code (or comments) that is longer than 80 characters in width. Most code editing tools default to a width of 80 characters, so viewing code wider than this makes for difficult viewing. Some compilers don't even compile code wider than 80 characters. C++ doesn't have any reasonable situations where code cannot be limited to fewer than 80 characters or broken up into several lines.

Statements: There should only ever be one statement per line of code. While the following is techincally valid C++ code, there is no valid reason for formatting your code this way:
int a = 0; cout << a << endl;
Some people, your instructor included, believe that it is best to declare only a single variable per line. We will not be grading you off if you choose not to adhere to this, but there are good reasons for it.

Blank lines should be used to break chunks of code into "thoughts." A "thought" in code is a related series of lines which, taken together, accomplish some small task. An example would be the three well-known lines in a swap function. If you were to embed the code for swapping two variables within your code, rather than in a function, those lines should be separated by whitespace, since they function on their own.
In general, a thought should not be more than about 10 lines of code.

Comments: Your code should be written primarily for human readers and only incidentally written for a machine to compile and execute. At a bare minimum this means:
- A one-line comment for every non-temporary variable declaration (that is, variables declared for the index in a for loop need not be commented, but everything else does.)
- A comment for every function describing its inputs, outputs, and general purpose. Be especially sure to mention when you alter variables that are passed by reference.
- At least one comment per "thought".
- Typical well-written and commented code runs between 15%-30% comments. Seriously.

Variable names are like comments on their own. Well chosen variable names can make life very easy for the reader. Poorly chosen variable names can make things hard. Maliciously chosen names can make things nigh impossible. Here are some things to remember:
- Variable names should be short, non-obvious, and information rich. numBytes is useful; numberOfBytesAllocated is unnecessarily long. myVal is useless, as it conveys absolutely no information. words is just plain malicious, as "word" is the technical term for a natively-understood quantum of information on a computer (x86 architectures have a 32-bit word size, for example).
- Variables composed of multiple words squished together may be composed in one of two standard ways: withInternalCapitals, which is the instructor's preferred method, or using_underscores, which is also common practice. Variants on these: AllWordsCapitalized, or Caps_And_Underscores are valid, but less common. Any other method may be used after explicitly debating it with the instructor, with the exception of alllowercase which is pureevil since it is hardtoread.
- Variables used in discussion and lecture will almost certainly include "foo," "bar," "baz," and others of a similar ilk. These are acceptable in discussion, since they have no inherent meaning, but not actually in your code, since they have no inherent meaning. For more information, see Foo in the Jargon File.

Spacing around operators: Spacing around operators is extremely useful for allowing a human reader to more easily see what you are doing. Operators should have a single space around them in the following cases:
- Arithmetic (+, -, %, /, *)
- Extraction/insertion, bit-shifting (<<, >>)
- Binary Boolean operations (&, &&, |, ||, ^)
- Comparison (==, !=, >=, <=)
- Assignment (=)
Operators should not have a space around them in the following cases:
- Array lookup ([])
- Pointer operations (*, &)
- Member extraction (., ->)
This list is not comprehensive, but other operators should be morally similar enough to one of the above that the question of spacing should be obvious. If in doubt, ask your instructor or TA.

Curly-braces: There are three styles of curly-brace placement that are acceptable. Choose which you prefer and be consistent:
```
The K&R style:
while (true) {
    ...
}

The Allman Style:
while (true)
{
    ...
}

The Emacs-default Style:
while (true)
  {
    ...
  }
```
For anything else, be prepared to argue with the instructor as to why your style is useful/sensible/valid.

Magic Numbers: Your code should not have any numeric constants in it with the possible exception of 0 and 1. The reason for this is best shown by example:
```
for (int i = 0; i < 100; i++)
{
    m[i] *= 100;
}
```
The code above is supposed to change units from centimeters to millimeters. Can you tell? Now consider the following:
```
for (int i = 0; i < NUM_MEASUREMENTS; i++)
{
    m[i] *= METERS_TO_CENTIMETERS;
}
```
Another nice reason is when you decide to change things later on, you only have one place to look, and can avoid possibly-inaccurate search/replace schemes. Imagine the headache when increasing the number of measurements your lab-helper program can handle from 100 to 10000 when you have the following line of code:
```
for (int i = 0; i <= 99; i++)
```
rather than
```
for (int i = 0; i <= NUM_MEASUREMENTS - 1; i++)
```
Spelling: Please get in the habit of spill chekcing yuor ritten werk fer this class, including email and code. Emacs has a very handy feature for this (Tools->Spell Checking->Shell-Check Comments). Proper spelling reflects well upon you as an educated person. Improper spelling, or the inclusion of chatroom abbreviations (u know who u r) reflect poorly. Your submissions will be run through the Emacs tool mentioned above, and points deducted accordingly.

Bad habits: There are two things that will instantly cause you to lose all style points for an assignment: using goto statements and the use of the "nested tri-graph" operator (AKA question-colon). For each of these there is one (and only one) acceptable usage, which will be covered in class, under proper adult supervision, by consenting adults, with proper lab equipment, fire crews standing by, and with the use of proper protection. These issues are not to be taken lightly: improper use of these language "features" can lead to unfathomably hard to understand code, hence their restricted status.