CMU 15-112: Fundamentals of Programming and Computer Science
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 global economy over $300 billion annually in 2013! (source)
  • Software errors have resulted in many spectacular failures (source)


• Good style reduces time spent debugging, and...
  
  • Around 75% of a developer's time is spent debugging (source)
  • Fixing a bug takes 30 times longer than writing a line of code (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... Note that lines that are blank or only contain comments do not count towards the 20-line/function limit.
   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 (including comments!). Indent properly. Use spaces, not tabs, with 4 spaces per indent level. Use standard whitespace, including one blank line between functions. Note that while comments do not count towards the 20-lines/function limit, they do count towards the 80-chars/line limit.
   7. Global Variables
      Avoid global variables.
   8. Magic Numbers
      Do not use magic numbers. In particular, every number besides -2, -1, 0, 1, 2, or 10 must generally be stored in a well-named variable. At the grader's discretion, we may not deduct points when other constants are used in what we deem to be a safe and clear manner, such as, say, x**0.5 for a square root when computing the quadratic formula. This is clear code, but it is also safely constant, because you would never want to use any other exponent in that specific case. Regardless, your safest bet is to follow the general rule above and just store constants in well-named variables.
   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"