-
Notifications
You must be signed in to change notification settings - Fork 6
Best Practices
In this section, we will discuss best practices for developing Python code. Specifically, we will cover documentation and testing.
import math
def f(u, v):
l = len(u)
s = 0
for i in range(l):
s += (u[i] - v[i]) ** 2
return math.sqrt(s)
Consider the function f
.
- Is it clear to you what this function does?
- Would you make any changes to the function to make its usage easier to understand?
In software development, documentation is crucial. It helps us, our collaborators, and future contributors understand how the code works and how it should be used.
There are several ways to document source code. The two main methods covered in this workshop are:
- Creating a "manual" for each part of your code.
- Using meaningful variable and function names.
import math
def euclidean_distance(u, v):
vector_length = len(u)
distance = 0
for i in range(vector_length):
distance += (u[i] - v[i]) ** 2
return math.sqrt(distance)
import math
def euclidean_distance(u, v):
"""
Computes the Euclidean distance between two vectors `u` and `v`.
The Euclidean distance between `u` and `v` is defined as:
sqrt{(u_1 - v_1) ^ 2 + ... + (u_n - v_n) ^ 2}
Parameters
----------
u : list
Input vector.
v : list
Input vector.
Returns
-------
euclidean : float
The Euclidean distance between vectors `u` and `v`.
"""
vector_length = len(u)
distance = 0
for i in range(vector_length):
distance += (u[i] - v[i]) ** 2
return math.sqrt(distance)
Now, consider the function euclidean_distance
. How can we be sure that it is correct?
We know that the Euclidean distance between the two vectors
u = (2, -1)
v = (-2, 2)
euclidean_distance(u, v)
assert euclidean_distance(u, v) == 5
The assert
statement is a quick and simple way to test our code, but there are
several packages that can enhance our testing process by providing additional
support. One such package is pytest
, which we will be discussing today.
To use pytest
, we'll create a new file for our function, euclidean.py
, and
another file for our tests, test_euclidean.py
. The key rule with pytest
is
that test functions must include the word "test" in their names. Your files should
look as follows.
euclidean.py
import math
def euclidean_distance(u, v):
"""
Computes the Euclidean distance between two vectors `u` and `v`.
The Euclidean distance between `u` and `v` is defined as:
sqrt{(u_1 - v_1) ^ 2 + ... + (u_n - v_n) ^ 2}
Parameters
----------
u : list
Input vector.
v : list
Input vector.
Returns
-------
euclidean : float
The Euclidean distance between vectors `u` and `v`.
"""
vector_length = len(u)
distance = 0
for i in range(vector_length):
distance += (u[i] - v[i]) ** 2
return math.sqrt(distance)
test_euclidean.py
import euclidean
def test_euclidean_distance():
u = (2, -1)
v = (-2, 2)
assert euclidean.euclidean_distance(u, v) == 5
Once you've implemented these files, you can easily run your tests by executing the following command in your terminal, assuming you are in a location where ls lists both files:
$ pytest test_euclidean.py
=================================================== test session starts ====================================================
platform darwin -- Python 3.11.3, pytest-7.3.1, pluggy-1.0.0
rootdir: /Users/glynatsi/src/test
plugins: anyio-3.5.0
collected 1 item
test_euclidean.py . [100%]
==================================================== 1 passed in 0.02s ====================================================