Best Practices

Things to Note

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

This document does not describe details of generic best practices.

This document is being created in steps and may not be comprehensive.

Development Approach

We recommend using test driven development. A test driven development approach forces the developer to understand exactly what the expected output of the changes should be.

Autoreduction follows the PEP 8 Style Guide for Python Code, and which make reference to PEP 257 on Docstring Conventions.

A style example is:

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

Another example is:

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.

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.

README.md

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.