Skip to content

Best Practices

Nikoleta Glynatsi edited this page Aug 19, 2024 · 4 revisions

In this section, we will discuss best practices for developing Python code. Specifically, we will cover documentation and testing.

Documentation

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.

  1. Is it clear to you what this function does?
  2. 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.

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

Adding a "Manual" for Each Part of Your Code

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)

Testing

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

image

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 ====================================================
Clone this wiki locally