CMU 15-112: Fundamentals of Programming and Computer Science
Class Notes: Style


Some Style Facts:


Style Rubric

  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"