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 (which are not OUR style guide):
  
  • The Official PEP-8 Python Style Guide
  • Google Python Style Guide
  • Many, many others...

1. 5-Point Style Issues
   
   1. Comments
      Not using any comments is a 5-point error; not using enough comments or having bad comments is just a 2-point error.
      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. Comments should also be used to explain any code that is not self-documenting.
   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.
      Use helper functions to break down the logic of a solution into several clear tasks. Read the Top-Down Design section to learn more about how to do this.
   3. Test Functions
      Not using any test functions (where appropriate) is a 5-point error; not using enough is just a 2-point error.
      You must write test functions for any function you write which is reasonably testable. Functions which are not reasonably testable include graphics functions, data initialization functions, and functions which return random results.
   4. Clarity
      Even if your code works, and is reasonably efficient, your logic must not be overly complex, particularly if a 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
      You must 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). Note that variable names should not overwrite built-in keywords; for example, str is a bad name for a string variable.
   3. Run-On Functions
      Use helper functions liberally. Do not have more than 20 lines in any one function (or 25 lines for functions in animation or graphics problems). While it is possible to have a well-written 20+ line function, we expect you to keep your functions at a reasonable length for this course. Note that lines that are blank or only contain comments do not count towards the 20-line/function limit.
   4. "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.
   5. Formatting
      Do not exceed 80 characters in any one line (including comments!). Indent properly. Use spaces, not tabs, with 4 spaces per indent level (most editors let you map tabs to spaces automatically). 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.
   6. Global Variables
      Within this course, avoid global variables.
   7. 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.
   8. Duplicate Code
      Do not duplicate code (instead of copy-pasting, place the code in a helper function).
   9. Dead Code
      Do not include any dead code (code that cannot ever be executed). Once you have finished debugging, remove any remaining debugging code from your function, even if it is commented out.
   10. Meaningful UI
       When appropriate, provide meaningful UI (clear prompts, clear output) for interactive programs.
   11. 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"