CS 10 Style Guide

• Consistency In much of the following we will present options for formatting your code. Where several options are presented, we do not care which your choose, SO LONG AS YOU ARE CONSISTENT. Consistency is the single 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.
  
  Part of consistency is the following: if editing someone else's code (which should not happen in this course!!!!) use their style. Your edits should be made as transparently as possible.
  
  
• 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 is right out...)
  
  Note that your editor needs to interpret the TAB (\t) character as 8 spaces (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.
  
  
• 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 TA included, believe that it is best to only declare 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. ask if you are curious.
  
  
• 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/redundant, 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, 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.
  
  
• Curly-braces There are three styles of curly-brace placement that are acceptable. Choose whichever you prefer, and then be consistent:

  The K & R style:
  while (1) {
      ...
  }
  
  The Allman Style:
  while (1)
  {
      ...
  }
  
  The Emacs-default Style:
  while (1)
    {
      ...
    }
  

  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;
  }
  

  Edit the above code to change units from centimeters to millimeters. Or, edit 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 into 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), as do all Windows packages. Proper spelling reflects well upon you as an educated person. Improper spelling, including 31337 / 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.