Computer Science
15-110, Fall 2010, Lecture 2
Style Facts and Style Rubric
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...
- Software errors cost the US economy about $60 Billion annually! (source)
- Software errors have resulted in many spectacular failures (source)
- Good style reduces maintenance costs, and...
- Only 10% of development costs go into writing code, the other 90%
into maintaining it (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:
- Many, many others... (including ours!)
Style RubricAt some to-be-determined point, we may grade for style, after which style will be worth about 10 to 15
points on each hw. Each style issue is either entirely right or not. So if you
have ONE line beyond 80 characters, then you lose the 2 style points for that
issue. If you have 50 lines beyond 80 characters, you do not lose 50x those
points. You just lose them once per issue.
While you may in theory lose up to 5*4 + 2*15 = 50
points, there are no negative style grades. Lowest style grade is 0.
- 5-Point Style Issues
- No syntax errors (even if your
code has logical errors or runtime errors!).
- Use correctly-named files with
correctly-named functions (where applicable)
(Note: simple rule -- it is at least a 5-point penalty if CA's must manually
edit your code to get the autograder to work) - Use comments
(Note: not using any comments is a 5-point error; not using enough
comments is just a 2-point error.) - Use top-down design with unit
testing
(Note: not using any helper functions (where appropriate) or any
test functions is a 5-point error; not using enough is just a
2-point error.)
- 2-Point Style Issues
- Include your name, andrew id, and
section in a comment at the top of every file you submit
- Use a clear, robust design
- Use meaningful variable and
function names (whenever possible)
- Use proper mixedCase/camelCase
naming, with the first letter in lowercase (eg: tetrisPiece)
- Include all obvious boundary
cases in test functions
- Use helper functions liberally
Do not have more than 20 lines in any one function (or 25 lines for
functions using canvas.data or graphics).
(While it is possible to have a well-written 20+ line function, we need a
simple hard-and-fast rule for grading purposes...) - Comment liberally but not excessively,
using clear language in comments
(Note: if you do not write any comments, then you lose 5 points
from the previous list and so this item would not apply here.) - Do not exceed 80-characters in
any one line
- Indent properly.
- Do not use magic numbers.
In particular, every number besides -2, -1, 0, 1, or 2 must be
stored in a well-named variable. - Do not be grossly inefficient
(You are generally not responsible for efficiency in 15-110, and you do not
have to use the most efficient solution in general; but the exception is
if you are truly "grossly" inefficient, particularly if your
approach is also unclear, and especially if you had simple, clear, and
reasonably efficient options to choose from.) - Do not duplicate code (instead of
copy-pasting, place the code in a helper function)
- When appropriate, provide
meaningful UI (clear prompts, clear output)
- Use "else" where
appropriate
So this code loses 2 points:
if (x < 2): foo()
if (x > 3): bar() # <- should be "elif" - Follow other guidelines as
described in the class notes