# ENGG1811 Style Guide

## Overview

### What is Style?

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.

### Style in ENGG1811

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.

### How to use this guide

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.

## Mandatory Style Guide

### Code Layout

Use the following order when laying out your code.

• Docstring
• Relevant module imports
• Definition of constants
"""
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!")


### Docstring Contents

All programs should have a docstring comment. It must include the following elements:

• Purpose: what is the aim of your code?
• Name
• Date created
• Method: how did you go about solving the problem?
• Data dictionary

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
"""


### Constant Naming

Constants should be named in all uppercase.
Constants should be reserved for values that are either:

• Always mathematically or scientifically true, e.g. 360 degrees in a circle, gravitational acceleration on earth is 9.81m/s2
• Defined in the specification as being constants.

All other terms should be defined as variables.

GRAVITY = 9.81

### Variable Naming

Variables 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 = 30

### Maximum line length

Keep 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:

1. Code within () [] {} can be spread over multiple lines.
2. Using the line continuation \ 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.

### Commenting

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 += 1

### Code complexity

Ensure 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) * d

## Recommended Style Guide

### Imports

Imports should be on separate lines.

# Do this
import numpy
import math

# Don't do this
import numpy, math

### Indentation

Between 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)

### Spacing

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+=1

### Declaring Variables

Variables 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


### Loop Variables

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 += 1

It is recommended variables controlling for loops be declared as part of the for loop.

for i in num_list:
# do something

### Commenting

Do 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 += 1

### Functions

#### Repeated Code

Do 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

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.

#### Return

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.