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 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 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)


• Some Style Guides (which are not OUR style guide):
  
  • The Official PEP-8 Python Style Guide
  • Google Python Style Guide
  • Many, many others...

1. Clarity Rules
   
   1. Ownership
      You must include your name, andrewId, and section in a comment at the top of every file you submit.
      This is good practice for later in life, when you will want to document all code that you contribute to projects.
      2-point error: not writing your name/andrewId/section in a submitted file
   
   
   2. Comments
      You should write concise, clear, and informative comments that supplement your code and improve understanding.
      Comments should be included with any piece of code that is not self-documenting.
      Comments should also be included at the start of every function (including helper functions).
      Comments should not be written where they are not needed.
      5-point error: not writing any comments at all.
      2-point error: writing too many or too few comments, or writing bad comments.
   
   
   3. Helper Functions (Top-Down Design)
      You should use top-down design to break large programs down into helper functions where appropriate.
      This also means that no function should become too long (and therefore unclear).
      5-point error: not using any helper functions (where helper functions are needed).
      2-point error: using too many or too few helper functions.
      2-point error: writing a function that is more than 20 lines long.
      • Exceptions: blank lines and comments do not count towards this line limit, and this rule does not apply to graphics functions and init()/run() functions in animations.
   
   
   4. Variable Names
      Use meaningful variable and function names (whenever possible).
      Variables and functions should be written in the camelCase format. In this format, the first letter is in lowercase, and all following words are uppercased (eg: tetrisPiece).
      Variable names should not overwrite built-in function names; for example, str is a bad name for a string variable. Common built-in keywords to avoid include dict, dir, id, input, int, len, list, map, max, min, next, object, set, str, sum, and type.
      5-point error: not having any meaningful variable names (assuming variables are used).
      2-point error: using some non-meaningful variable names.
      • Exceptions: i/j for index/iterator, c for character, s for string, and n/x/y for number.
      2-point error: not using camelCase formatting.
      2-point error: using a built-in function name as a variable.
   
   
   5. Unused Code
      Your code should not include any dead code (code that will never be executed).
      Additionally, all debugging code should be removed once your program is complete, even if it has been commented out.
      2-points error: having any dead or debugging code.
   
   
   6. Formatting
      Your code formatting should make your code readable. This includes:
      
      • Not exceeding 80 characters in any one line (including comments!).
      • Indenting consistently. Use spaces, not tabs, with 4 spaces per indent level (most editors let you map tabs to spaces automatically).
      • Using consistent whitespace throughout your code.
        • Good whitespace: x=y+2, x = y+2, or x = y + 2
        • Bad whitespace: x= y+2, x = y +2, or x = y   + 2
      2-point error: having bad formatting in any of the ways described above.
   
   
2. Robustness Rules
   
   1. Test Functions
      You should always write test functions for each function that is reasonably testable.
      At the beginning of the semester we provide some test functions in the homework starter files, but we will phase these out over time. You should start supplementing our tests with your own as of hw3.
      5-point error: not writing any test functions.
      2-point error: not writing enough test functions.
      • Exceptions: you do not need to test interactive, random, graphics, data initialization, or event functions.
   
   
   2. Efficiency
      As this is an introductory course, we do not expect you to write the most efficient solutions generally. However, your code may not be "grossly" inefficient, especially if you had simple, clear, and reasonably efficient options to choose from.
      5-point error: writing a function that works correctly but takes more than 30 seconds to test (with some exceptions).
      2-point error: writing a function that works correctly but takes more than 5 seconds to test (with some exceptions).
   
   
   3. Repetitive Code
      In general, you should not have repetitive code.
      One example of this is duplicate code, code that has been copy-pasted. This should instead be put into a helper function.
      Another example is "numbered"-code, where there are multiple variables like foo0, foo1, foo2. These should be represented by a loop or list instead.
      5-point error: having 10 or more instances of repeated code.
      2-point error: having 3 or more instances of repeated code.
   
   
   4. Magic Numbers
      A magic number is a number used outside of a variable assignment in code that does not have an immediate and clear meaning.
      In general, every number besides -1, 0, 0.5, 1, 2, and 10 is magic.
      If you must use a magic number, store the number or an expression using the number in a variable, then use that variable.
      2-point error: using any magic numbers.
   
   
   5. If/Else Statements
      When reasonable, multiple if statements should be joined into an if-elif-else chain. For example, the following code:

          if (x < 2):
              foo()
          if (x > 10):
              bar()
          if (2 <= x <= 10):
              oh()
      

      should be

          if (x < 2):
              foo()
          elif (x > 10):
              bar()
          else:
              oh()
      

      2-point error: not joining-up multiple ifs where appropriate.
   
   
   6. Global Variables
      Global variables can be useful while programming, but you will not need them in 15-112.
      In fact, if you use global variables in this class, you're probably using them incorrectly.
      2-point error: using any global variables.