CMU 15-112: Fundamentals of Programming and Computer Science
Class Notes: Style
Some Style Facts:
- 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...
- Good style reduces time spent debugging, and...
- 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:
- 5-Point Style Issues
Not using any comments is a 5-point error; not using enough comments is just a 2-point error.
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.
Not using any test functions (where appropriate) is a 5-point error; not use enough is just a 2-point error.
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.
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-Point Style Issues
Include your name, andrew id, and section in a comment at the top of every file you submit
Use meaningful variable and function names (whenever possible), with proper mixedCase/camelCase naming, with the first letter in lowercase (eg: tetrisPiece)
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.
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.
"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.
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.
Avoid global variables.
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.
Do not duplicate code (instead of copy-pasting, place the code in a helper function).
Do not include any dead code (code that cannot ever be executed).
When appropriate, provide meaningful UI (clear prompts, clear output)
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"