Computer Science 15-112, Spring 2013
Class Notes:  Style

• Good style is...
  • Both an art and a science.
  • Open to some debate, yet mostly agreed upon.
  • The product of years of suffering due to bad style.
     
• Good style reduces errors, and...
  • Software errors cost the US economy about $60 Billion annually way back in 2002! (source)
  • Software errors have resulted in many spectacular failures (source)
     
• Good style reduces maintenance costs, and...
  • Only 10% of development costs go into writing code, the other 90% into maintaining it (source)
     
• Good style will...
  • Help you get an "A"
  • Help you get a "job"
  • Help you be happy, healthy, prosperous, and keenly admired by all.

• Some Style Guides:
• The Official PEP-8 Python Style Guide 
• Google Python Style Guide
• Many, many others... (including ours!)

1. 5-Point Style Issues
1. Comments
   Not using any comments is a 5-point error; not using enough comments is just a 2-point error.
2. Helper Functions (Top-Down Design)
   Not using any helper functions (where appropriate) is a 5-point error; not using enough is just a 2-point error.
3. Test Functions
   Not using any test functions (where appropriate) is a 5-point error; not use enough is just a 2-point error.
4. Clarity
   Even if your code works, and is reasonably efficient, your logic must not be overly complex, particularly if reasonably clear and straightforward options exist, which they nearly always will in this course.  Many of the 2-point issues below involve clarity, but the 5-point version is reserved for especially gross violations.
5. Efficiency
   This being 15-112, you do not have to use the most efficient solution in general; but your code may not be "grossly" inefficient, particularly if your approach is also unclear, and especially if you had simple, clear, and reasonably efficient options to choose from.
    
2. 2-Point Style Issues
1. Ownership
   Include your name, andrew id, and section in a comment at the top of every file you submit
2. Meaningful Names
   Use meaningful variable and function names (whenever possible), with proper mixedCase/camelCase naming, with the first letter in lowercase (eg: tetrisPiece)
3. Comments
   Use concise, clear, and informative comments where needed (and do not use comments where unneeded), especially at the start of functions or other obvious logical blocks of code, and also to explain any code that is not self-documenting.
4. Run-On Functions
   Use helper functions liberally  Do not have more than 20 lines in any one function (or 25 lines for functions using graphics or events).  While it is possible to have a well-written 20+ line function, we need a simple hard-and-fast rule for grading purposes...
5. "Numbered" Variables (Avoiding Loops and Lists)
   This entails making code unnecessarily complex, or simply verbose and amateurish, by avoiding using loops or lists.  This is most often typified by using variables with consecutive numeric suffixes, as in foo0, foo1, foo2, etc.  Extreme violations may qualify for the 5-point clarity violation above.
6. Formatting
   Do not exceed 80-characters in any one line.  Indent properly.  Use spaces, not tabs, with 4 spaces per indent level.  Use standard whitespace, including one blank line between functions.
7. Global Variables
   Avoid global variables.
8. Magic Numbers
   Do not use magic numbers. In particular, every number besides -2, -1, 0, 1, or 2 must be stored in a well-named variable.
9. Duplicate Code
   Do not duplicate code (instead of copy-pasting, place the code in a helper function).
10. Dead Code
    Do not include any dead code (code that cannot ever be executed).
11. Meaningful UI
    When appropriate, provide meaningful UI (clear prompts, clear output)
12. Et Cetera
    Follow other guidelines as described in the class notes
    For example:  Use "else" where appropriate
    So this code loses 2 points:
      if (x < 2): foo()
      if (x > 3): bar() # <- should be "elif"