Style Guide 👀

Style Requirements

You will be graded for the style of programming on this assignment. A few key requirements for style are given below (textbook, Chapter 1.3.5):

This is complete Python style guide: Python Style Guide.

We will grade style on a smaller set of rules:

• Function names are lowercase, with words separated by underscores. Descriptive names are encouraged.
• Function names typically evoke operations applied to arguments by the interpreter (e.g., print, add, square) or the name of the quantity that results (e.g., max, abs, sum).
• Parameter names are lowercase, with words separated by underscores. Single-word names are preferred.
• Parameter names should evoke the role of the parameter in the function, not just the kind of argument that is allowed.
• Single letter parameter names are acceptable when their role is obvious, but avoid “l” (lowercase ell), “O” (capital oh), or “I” (capital i) to avoid confusion with numerals.
• Every method should have a docstring.
• Avoid using magic numbers (that is numbers except 0, 1, -1). If you need to use, say, 17 in your code, create a variable with the meaningful name, set it to 17 and use a variable instead.
• Limit all lines to a maximum of 79 characters.
• Indentation: Use 4 SPACEs, no TABs.
• Each input has an associated assert statement.
• Variable names conform to the snake case naming scheme and are sufficiently descriptive.
• There must be a newline at the end of any python file submitted.

Checking style

In order to check the style of your code you need to install 3 programs:

• pycodestyle (tool to check your Python code against some of the style conventions)
• pylint (source code, bug and quality checker for the Python. Has more options compared do pycodestyle)
• pydocstyle (tool for checking compliance with Python docstring conventions) To install:
  Note: Some of the programs (linters) maybe come preinstalled.
  1) Open terminal
  2) type pip install pycodestyle
  3) type pip install pylint
  4) type pip install pydocstyle

To run these programs, you simply type in the name of the program and the file that you wish to run it on e.g.:

>>> pylint hw01.py

You will receive a fairly long-winded output, but feel free to ignore parts of it that don’t seem relevant to our style guide. For example, here are the results from one of my files, where I cross out the parts that I feel are irrelevant:
***** Module hw01solutions
hw1solutions.py:8:64: C0303: Trailing whitespace (trailing-whitespace)
hw1solutions.py:21:0: C0303: Trailing whitespace (trailing-whitespace)
hw1solutions.py:36:23: C0326: Exactly one space required after comma
    assert isinstance(x,int), “first argument must be an integer”
                       ^ (bad-whitespace)
hw1solutions.py:37:23: C0326: Exactly one space required after comma
    assert isinstance(y,int), “second argument must be an integer”
                       ^ (bad-whitespace)
hw1solutions.py:38:12: C0326: Exactly one space required around comparison
    assert x>0, “first argument must be positive”
            ^ (bad-whitespace)
hw1solutions.py:39:12: C0326: Exactly one space required around comparison
    assert y>=x, “second argument must be >= the first one”
            ^ (bad-whitespace)
hw1solutions.py:40:0: C0303: Trailing whitespace (trailing-whitespace)
hw1solutions.py:45:30: C0326: Exactly one space required after comma
        for divisor in range(2,int(n*sqrt_factor)+1):
                       ^ (bad-whitespace)
hw1solutions.py:50:20: C0326: Exactly one space required after comma
    for n in range(x,y+1):
                       ^ (bad-whitespace)
hw1solutions.py:77:42: C0303: Trailing whitespace (trailing-whitespace)
hw1solutions.py:89:18: C0326: No space allowed before bracket
def numbered_rows (levels = 10):
                    ^ (bad-whitespace)
hw1solutions.py:89:26: C0326: No space allowed around keyword argument assignment
def numbered_rows (levels = 10):
                    ^ (bad-whitespace)
hw1solutions.py:93:28: C0303: Trailing whitespace (trailing-whitespace)
hw1solutions.py:94:33: C0303: Trailing whitespace (trailing-whitespace)
hw1solutions.py:95:34: C0303: Trailing whitespace (trailing-whitespace)
hw1solutions.py:96:35: C0303: Trailing whitespace (trailing-whitespace)
hw1solutions.py:97:36: C0303: Trailing whitespace (trailing-whitespace)
hw1solutions.py:98:36: C0303: Trailing whitespace (trailing-whitespace)
hw1solutions.py:99:36: C0303: Trailing whitespace (trailing-whitespace)
hw1solutions.py:100:36: C0303: Trailing whitespace (trailing-whitespace)
hw1solutions.py:101:36: C0303: Trailing whitespace (trailing-whitespace)
hw1solutions.py:102:39: C0303: Trailing whitespace (trailing-whitespace)
hw1solutions.py:105:15: C0303: Trailing whitespace (trailing-whitespace)
hw1solutions.py:106:15: C0303: Trailing whitespace (trailing-whitespace)
hw1solutions.py:107:16: C0303: Trailing whitespace (trailing-whitespace)
hw1solutions.py:108:17: C0303: Trailing whitespace (trailing-whitespace)
hw1solutions.py:115:20: C0326: Exactly one space required after comma
        print(n, “”,’ ‘.join(out_base),””)
                   ^ (bad-whitespace)
hw1solutions.py:115:39: C0326: Exactly one space required after comma
        print(n, “*”,’ ‘.join(out_base),””)
                                   ^ (bad-whitespace)
hw1solutions.py:26:0: C0103: Argument name “x” doesn’t conform to snake_case naming style (invalid-name)
hw1solutions.py:26:0: C0103: Argument name “y” doesn’t conform to snake_case naming style (invalid-name)
hw1solutions.py:44:4: C0103: Argument name “n” doesn’t conform to snake_case naming style (invalid-name)
hw1solutions.py:50:8: C0103: Variable name “n” doesn’t conform to snake_case naming style (invalid-name)
hw1solutions.py:113:8: C0103: Variable name “n” doesn’t conform to snake_case naming style (invalid-name)
——————————————————————
Your code has been rated at 0.83/10 (previous run: 0.28/10, +0.56)
From above, we can see that we don’t care about the invalid names or the trailing whitespaces. We might care about the bad-whitespaces, so I might choose to fix those. It’s really personal judgement that matters for how you parse these results. Effectively, we can conclude that the previous code is good enough for submission, since there were no major errors.

Following, we can see some examples of warnings that we would actually care about.

(py36) Alexanders-MacBook-Pro-3:hw1 alexanderpotapov$ pylint terribleCode.py
***** Module terribleCode
terribleCode.py:6:0: C0305: Trailing newlines (trailing-newlines)
terribleCode.py:1:0: C0103: Module name “terribleCode” doesn’t conform to snake_case naming style (invalid-name)
terribleCode.py:1:0: C0111: Missing module docstring (missing-docstring)
terribleCode.py:1:0: C0103: Function name “ALLCAPSFUNC” doesn’t conform to snake_case naming style (invalid-name)
terribleCode.py:1:0: C0111: Missing function docstring (missing-docstring)
terribleCode.py:3:4: C0103: Variable name “other_VARIABLE” doesn’t conform to snake_case naming style (invalid-name)
terribleCode.py:4:4: C0103: Variable name “o” doesn’t conform to snake_case naming style (invalid-name)
terribleCode.py:5:4: C0103: Variable name “l” doesn’t conform to snake_case naming style (invalid-name)
terribleCode.py:1:16: W0613: Unused argument ‘lst’ (unused-argument)
terribleCode.py:3:4: W0612: Unused variable ‘other_VARIABLE’ (unused-variable)
terribleCode.py:5:4: W0612: Unused variable ‘l’ (unused-variable)
————————————-
Your code has been rated at -12.00/10
As we can see, we are actually failing a lot of the requirements that were set forth in the style guide. We’ve used random capital words, we’ve used bad variable names, and we’re missing docstrings, so we’ve made a good few mistakes. You would want to fix these before turning in your code. One thing that we cannot use these autocheckers to check are magic numbers and indentation. That must be checked manually by yourself.
In conclusion, these are nice tools, but they will not make up for not keeping proper track of your code and making good style choices while writing. Best of luck and feel free to ask on piazza if you have any other questions.