Introduction

Welcome to this short course which will introduce you to some techniques and processes which are essential if you are going to be developing professional-quality software.

For this course we will be focusing on three main topics:

  1. documentation
  2. testing
  3. licensing

and discussing why they’re important and how to integrate them into your code. We will explore these concepts in Python, but the ideas apply to all programming languages. You can do documentation and testing in C, C++, R, Fortran, Julia, Go and Rust, but each has its own tools and techniques. Languages which make these things easy are good languages for software development.

For the purpose of this course we will be using a free tool called JupyterLab which provides you with a local editor and Python terminal in your web browser. Setting up instructions can be found here.

Intended learning outcomes

By the end of this course, you will:

  • Know how to document your Python functions and modules
  • Write test functions and automate them
  • Know how to do testing with multiple data
  • Understand the principles of licensing code

How to read this documentation

In this documentation, any time that we are seeing a small snippet of Python code, we’ll see it written in a grey box like the following:

print("Hello, Python")

If the commands are executed, their output is shown below the code, marked by a vertical purple line:

print("Hello, Python!")
Hello, Python!

By contrast, larger pieces of code are shown as scripts with a given name, e.g. script.py, in a code block with a darker header:

script.py
greeting = "Hello"
name = input("What is your name? ")
print(greeting, name)

We may ask you to run a script using the Command Prompt (Windows) or Terminal (Mac and Linux). We will show you what commands to run and will look like this:

Terminal/Command Prompt
python script.py

Please note that we sometimes skip showing the execution of scripts in the Terminal/Command Prompt box, but you are expected to run the script on your own machine.

In some cases we will introduce general programming concepts and structures using pseudocode, a high-level, easy-to-read syntax close to natural language. This should not be confused with Python code and cannot be executed on your machine, but it is useful to describe how your code should behave. Here there is an example:

FOR EACH sample IN my_study
    IF (sample.value > 100)
        DO SOMETHING
    OTHERWISE
        DO SOMETHING ELSE

There are some exercises along this course, and it is important that you try to answer them yourself to understand the concepts. Exercises are shown in blue boxes, followed by a yellow box containing the answer. We recommend you attempt each exercise before looking at the solution.

Exercise

This is an exercise. You will need to click in the below box to see the answer.

This is the answer.

Last, we will highlight important points using green boxes like this one:

Key points

These are important concepts and technical notes.