Best Practices

Things to Note

This document describes the best practices for developing for The Autoreduction Project.

This document does not describe generic Python best practices.

Autoreduction follows the pep8 standard which you should look into in your own time if not already familiar with.

Development Approach

When developing for Autoreduction, we advise that whenever possible, a test driven development approach should be adopted.

A test driven development approach forces the developer to understand exactly what the expected output of the changes should be. Knowing what the output should be allows for easier design and development to achieve the desired functionality.

Classes

• New classes should contain relevant methods for that class object only - I.E. we treat classes as objects - Not just a means to containing unrelated methods to be used separately.
• Class names should be descriptive of their purpose.
• Classes should also have a descriptive docstring following the below format:

Format

<Class description - what the class is> 
Usage: <when to use>

Example

class Logger:
	“””
	Creates a custom logger object
	Usage: Direct replacement for built-in logger 
	”””

Methods

• Should be descriptively named (ideally no abbreviations)
• Method location is relevant and makes sense with the flow of code execution.
• Small in size - ideally no larger than 20 lines
• Generic and modular in design (easily re-useable to allow for DRY programming)
• Contains a descriptive docstring following the below format:

Format

<description of method>
:param <param name>: (type) <description>
:return <return name>: (type) <description>
:raises <exception>: <description>

Example

def addition(number1, number2)
	“””
	Add 2 numbers together
	:param number1: (int) a number perform addition with
	:param number2: (int) a number to perform addition with
	:return (int) result of adding number1 and number2 together
	:raises ValueError: raise if arguments are not integers
	”””
	try:
		return number1 + number2
	except TypeError as exp:
		raise exp

Unit Tests

Unit tests should be small, modular and descriptive in size. The less that has to be mocked, the better the method and the better the test.

Docstrings should follow the below format:

Test: <What you are testing>
When <under what pretences e.g when myfunc() called with valid arguments>

The purpose of this format is to force tests to be small and to the point. If the test can’t be correctly documented using this format, too many elements are being tested at once and should be broken down further.

Documentation

Each package (existing and newly developed) should contain a README.md file describing the following points:

• What the package is
• The purpose of the package
• Package contents
• Package usage with examples

Please ensure when developing new packages to include a detailed README.md. This also applies when making changes to an existing package to update the README.md where applicable.

Should a README.md file not exist within a package, create an issue to make one.