CSCA08H3 S 20241:Introduction to Compuer Science I

python_style_guide

CSCA08H Style Rules

For assignments in this course, you will be marked not only on whether your code works, but also on style. Here are some guidelines.

Formatting Style

1. Use Python style conventions for your function and variable names. This means that you should use pothole case: lowercase letters with words separated by underscores ( _ ) to  improve readability. For example, the variable name  dog_name is good but  dogName is not.

2. Choose meaningful names for your functions and variables. For example,  num_bright_spots is more helpful and readable than  nbs .

3. Do not use the tab character to indent code. Instead, use four spaces for each indentation

level. Note that you can configure WingIDE to include four spaces for each tab character that you type.

4. Put a blank space before and after every operator. For example, the first line below is good but the second line is not:

5. For each function, write a docstring according to our design recipe. (See below for guidelines on the content of your docstrings.)

Put the docstring's closing quotation marks on their own line.

6. Each line must be less than 80 characters long including spaces. In Wing, the red vertical line indicates 80 characters. You should break up long lines as follows:

 If the line contains comma-separated items (such as in a function call), type enter after a comma to continue on the next line like this:

 Triple-quoted strings (such as docstrings) can span multiple lines by typing enter anywhere within the string:

string."""

 For other situations, you can use parentheses to signal that the statement continues on the next line:

7. Within a docstring, put a blank line between the description and the examples.

8. Put a blank line between the docstring and the function body.

Programming Style

1. Do not compare a Boolean expression to  True  or to  False . For example, the first is good, the second is not:

2. Replace if statements of this form:

if x > 100:

return True

else:

return False

with a single-line statement like this:

3. Replace if statements of this form:

with a single if statement like this:

if x <= 100:

n = n + 1

4. Avoid duplicate code by calling on helper functions.

5. Each function body should contain 20 or fewer lines of code, including blank lines. (This 20 lines does not include the docstring.) If a function body is too long, break the function into helper functions and call those instead. Do not make it shorter by deleting blank lines or otherwise sacrificing readability!

Commenting

We frequently see CSCA08 students "over-commenting", by adding comments for every line of code. Please don't do this: assume the reader of the code is a proficient Python programmer. If you have at most one comment per logical chunk of code (whether that is a small function or a  coherent piece of a larger function), you're on-track. You can use the starter code provided, as  well as examples covered in class, to get a sense of how much commenting is too much.

Docstring

Follow the design recipe for writing functions. This means that in addition to the header and body, you must include a docstring with at least two examples, a description, and preconditions if applicable. Follow these rules when writing the description portion of the docstring:

1. Describe precisely what the function does.

2. Do not reveal how the function does it.

3. Make the purpose of every parameter clear.

4. Use the name of every parameter.

5. For functions that return values, be clear on what the return value represents.

6. Explain any conditions that the function assumes are true. These conditions should not refer to type requirements, because those are already covered by the type contract. However, sometimes there are conditions not covered by types, and you should include those. For example, if a function requires parameters  x and  y to be even, include  x and y are both even .

7. Be concise and grammatically correct.

8. Write the description as a command (e.g.,  Return the first ... ) rather than a statement (e.g.,  Returns the first ... )