CSCA08 Assignment Style Rules
CSCA08 Assignment Style Rules
Hello, dear friend, you can consult us at any time if you have any questions, add WeChat: THEend8_
Python Style Guideline for CSCA08
CSCA08 Assignment 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: letters are lowercase 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.
4. Put a blank space before and after every operator. For example, the first line below is good
but the second line is not:
b = 3 > x and 4 - 5 < 32
b= 3>x and 4-5<32
5. For each function, write a docstring according to our design recipe. (See below for guidelines
on the content of your docstrings.)
Put the function docstring's closing quotation marks on their own line.
6. Each line must be less than 80 characters long including spaces. (Exception: docstring
examples can be longer when necessary.) In Wing, the red vertical line usually 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:
min(1, 2,
3, 4)
Triple-quoted strings (such as docstrings) can span multiple lines by typing enter anywhere
within the string:
"""This is
a multi-line string.
The last character is the
newline character.
"""
For other situations, you can use the continuation character \ to signal that the statement
continues on the next line:
my_very_long_variable = 1000000000000000000000000000 + 10 + 9 + 8 + 7 + 6 + 5 \
+ 4 + 3 + 2 + 1
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.
9. Use two blank lines to separate functions.
Programming Style
1. Do not compare a Boolean expression to True or to False. For example, the first is good, the
second is not:
if a and b:
return 100
if (a and b) == True:
return 100
2. Replace if statements of this form:
if x > 100:
return True
else:
return False
with a single-line statement like this:
return x > 100
3. Replace if statements of this form:
if x > 100:
n = n
else:
n = n + 1
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. (The 20
lines do 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
For complicated bits of code inside functions, please add an internal comment to explain how the
code works. 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.
1. Use comments to explain tricky spots in the code.
2. Use comments to explain the meaning of a variable, if it is subtle. A good variable name can
go a long way. For example, "num_students" tells you more than just "num". But sometimes
the meaning is subtle enough that the variable name can't fully convey it (without being
ridiculously long!). For instance, you might have a variable called "next" and a comment that
says "The index within s1 from which to search for the next occurrence of s2."
3. Use comments to explain what you know is true at key moments. For example, after a while
loop has ended, you know that the loop condition has failed. There are often crucial
implications from this that require some reasoning to see. Write those down!
4. Use comments to summarize chunks of code. For example, if 5 lines of code as a whole
accomplish some task, it can be helpful to have a short comment summarizing that task. Of
course, if you use helper functions well, this won't be necessary terribly often.
5. Do not write comments that simply rephrase a line of code in English. For example "Increase
n by one" does not add anything that "n = n + 1" doesn't already say.
6. Do not write a comment for every line of code. That's too much. Instead, use the guidelines
above to decide when a comment is appropriate.
Docstring
Follow the design recipe for writing functions. This means that in addition to the header and body,
you must include a docstring with a description and example. 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 preconditions should not
refer to type requirements, because those are already in the function header. However,
sometimes there are conditions not covered by types, and you should include those.
if a function requires parameters x: int and y: int to be even and parameter s:
str to not be empty, include lines like
Precondition: x and y must both be even.
len(s) > 0.
after the description and before the example.
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 ... )