Programming style refers the set of guidelines used when writing code for a computer program. Following good style practices will help with the readability of your code, which allows us as markers to better understand what you are trying to achieve.
In this course, style is only assessed in assignments, however it is recommended that good style is used throughout your weekly lab exercises and exams as well.
This guide is divided into two sections: the first being the Mandatory Style Guide
, and the second being the Recommended Style Guide
. As the names suggest, in order to obtain full marks for the style portion of your assignment you must adhere to the mandatory guide. To increase the readability of your code (which will help us as markers), you may additionally follow the recommended style guide.
Use the following order when laying out your code.
"""
Purpose: Find the average of 3 numbers
Author: Alicia Shih
Date: 21/09/2022
"""
# Import modules
import math
# Constants are defined here
DEGREES_IN_CIRCLE = 360
# Remainder of code
print("Hello world!")
All programs should have a docstring comment. It must include the following elements:
The data dictionary should contain all the important variables and constants defined, their datatype (float, string, int) and a short description of what they are.
"""
Purpose: To calculate the average of 3 numbers
Author: Alicia Shih
Date: 21/09/2022
Method: Sums up the 3 numbers and then divides the
result by 3
Data dictionary:
[float] number_1 The first number
[float] number_2 The second number
[float] number_3 The third number
[float] average The average of the 3 numbers
"""
Constants should be named in all uppercase.
Constants should be reserved for values that are either:
All other terms should be defined as variables.
GRAVITY = 9.81Variables should be named either using snake_case or camelCase, you can choose the case style that you prefer. Please ensure that you use only one case style in your code and do not use a combination of them. Note that both case styles start with a lowercase letter.
Descriptive variable names should always be used where possible. Short variable names such as x or i are acceptable if there is no apporpriate long descriptive name (which is often for variables used as loop counters).
speed = 80
angle = 30Keep lines under 80 characters. Note that this extends to docstrings and comments. Break up long lines to keep them under 80 characters unless keeping it as a longer line is signficantly more readable. Python has two methods for you to break a long line of code into multiple lines:
\ symbol Line breaks should occur before the binary operator because this aims readability.
# Do this
sum = number_1 + number_2 \
+ number_3
# Don't do this
sum = number_1 + number_2 + \
number_3
We want to point out that Spyder has a visual aid to tell you whether you are using long lines. The Spyder editor has a vertical line, see picture below. The default set up in Spyder that there is room for 79 characters to the left of the vertical line. If all your text is to the left the vertical line, then all your lines of text have less than 80 characters.
Comments should be used to describe, explain and/or justify code; they should not simply restate what the code is doing. They should also be succinct and as short as possible. Comments should be accurate and agree with the code they describe. If you modify some existing code, you should ensure that the surrounding comments are still accurate.
# Count is only increased if value is even
if value % 2 == 0:
count += 1Ensure that your code is as simple as possible - don't use a long winded algorithm to do something simple.
# For example, instead of doing
a * d + b * d + c * d
# Do this
(a + b + c) * dImports should be on separate lines.
# Do this
import numpy
import math
# Don't do this
import numpy, mathBetween any function, if/else, or loop statement, the indentation level should increase by 1 stop. This is either one tab or four spaces.
# Indentation increases by 1 tab/four spaces
for i in num_list:
print(i)The arguments of long function calls should be aligned if they span over multiple lines.
# Function arguments are aligned here
if something and something_else and something_else_again \
and another_thing and too_many_things_here:
print(1)Include a space on each side of binary operators such as:
= + - * / // % < > <= >= == !=
Include a space on each side of Boolean operators such as:
and or not
Include a space before open brackets and after closing brackets:
if (a == b) and (b == c)
Include a space on each side of compound operations such as:
+= -= *= /=
# This is correct
if (a == b) and (b == c):
a = b + c
b += 1
# This is not correct
if (a==b)and(b==c):
a=b+c
b+=1Variables should be declared when (or close to when) they are first assigned a value, and close to when they are first used.
# Do this
i = 0
for j in num_list:
i += j
# Don't do this
i = 0
# ... lots of code not involving i ...
for j in num_list:
i += j
It is recommended variables controlling while loops be declared before the loop and used only to control that loop.
i = 0
while i < threshold:
# do something
i += 1It is recommended variables controlling for loops be declared as part of the for loop.
for i in num_list:
# do somethingDo not use trailing comments (i.e., comments which appear at the end of a line containing other code) unless the comment is very short and describes only the code that it appears next to.
# Do this
# Increase value of a until it equals b
if a != b:
a += 1
# Don't do this
if a != b: # Increase value of a until it equals b
a += 1Do not cut-and-paste code. The same code should not appear twice in your program. Avoid repeating code by defining a function and calling it twice (or more).
This is because repeated code makes your program hard to read and to modify.
Every function must have a comment placed before the function implementation describing the purpose of the function and any side-effects the function has. Note: You do not need to do this for functions that have already been provided to you.
# Return quotient of all values in list
# Returns None if there is division by zero
def quotient(num_list):Function names should be descriptive, typically containing multiple words.
Names for most functions (exceptions below) should be in snake_case. This should be consistent with your style for variable names.
Do not overuse return statements.
Use multiple returns only if this makes your function less complex or more readable.
For example, it is acceptable to have an early return statement(s) to handle error conditions or special cases, as well as another return statement for the computation of the function's main result.