Introduction to Python for Computational Science, Hans Fangohr, Max Planck Institute for the Structure and Dynamics of Matter & University of Southampton

Checklist

For every function you are writing, consider the following suggestions to remove as many errors from your work as possible:

have you tested your functions? Call them with varying values from the Python prompt and predict what answer you expect. If the answer that your function returns is different, you need to investigate. (Predict the answer before you call the function.)
- Where possible, use special cases for which you know the correct answer.
- Where example usage has been given in the instructions, make sure that when you call your function with the input values given in the example, you get the return values as given in the example.
have you documented your function (and used the help function to check that this is working) appropriately?

See also What makes a good documentation string?

Not documenting functions is an error. Documentation that exists but is wrong is also considered a bug in software engineering.
has your function exactly the name that is requested? Because an automatic system will test your file, the names have to be absolutely identical.
Is your source file styled according to the PEP8 guidance? You should Strive for PEP8 Compliance and tell Spyder to warn you if your code doesn’t follow the PEP8 style guide
Does your function execute ‘silently’? While there are exceptions to this rule, we normally expect that functions do not print anything (although they would normally return an object of some type).
Is your file syntactically correct? You can test this by executing your file (let’s say it is called training1.py if you are working on training 1 exercise in the first lab) using Python (for example by pressing F5 in Spyder). If there is a syntax error in the file, Python will raise an error message at this point.

[Often, it is okay (or even desired) that your file will not produce any output if run in this way; for example if the file just contains a set of functions, which are never called within the file.]
You may want to use the %reset command in IPython shells (at least once) before running your program test: this will make sure you are not referring to objects that are defined in the interpreter session but not in your file.

What makes a good documentation string?

A good documentation string comments on (i) the parameters given to the function, (ii) the return value of the object and (iii) what the function does to get from the parameters to the return value.

Additional information may include examples, type information, exceptions the function may raise, information about the algorithm used, etc.

Here is a minimalistic example:

def average(a, b):
    """Compute and return the arithmetic mean of inputs.

    Given parameters a and b, return the arithmetic mean.compute and
    return the arithmetic mean of a and b."""
    return (a + b) * 0.5

A more detailed example:

def mysum(a, b):
    """Return the sum of parameters a and b.

    Parameters
    ----------
    a : numeric
        first input
    b : numeric
        second input

    Returns
    -------
    a+b : numeric
        returns the sum (using the + operator) of a and b. The return type will
        depend on the types of `a` and `b`, and what the plus operator returns.

    Examples
    --------
    >>> mysum(10, 20)
    30
    >>> mysum(1.5, -4)
    -2.5

    Notes
    -----
    History: example function first created 2002, last modified 2013
    """
    return a + b

As a minimum guidance, the documentation string should explain what the parameters are (and use of the word parameters is encouraged) and what the function returns (and use of the word return is encouraged).

Going beyond this, the documentation string needs to provide a reasonable summary of (i) what the function does and (ii) what restrictions there are on the valibity of results or values of parameters. One needs to use common sense here. You may want to use python’s help function or Spyder’s object explorer to see examples of documentation strings from in-built Python commands or library functions.

For the short practice functions we write in this course, the documentation string may often seen unnecessary, but it is good practice to create at least a short documenation string that explains what the parameters and return values are.

A more detailed discussion of documentation style conventions is available for the

PEP257 style
numpydoc style and the

You can instruct Spyder to highlight deviations from documentation string conventions: Preferences -> Completion and linting -> Docstring style -> [ ] Enable docstring linting (you can choose Numpy or PEP2 257 convention).

Advanced suggestions

Slightly advanced suggestion:

If you want to add some code to your file that calls your functions (maybe for you to have suite of tests that can be run quickly), you can add the following template at the end of the file (below all function definitions):
```
if __name__ == "__main__":
    pass  # add your testing code here.
```
Here is an example for training1.py calling the function average that we provide for you:
```
def average(a, b):
    """Given Parameters a and b, compute and
    return the arithmetic mean of a and b."""
    return (a + b) * 0.5

# main program starts here
if __name__ == "__main__":
    print("Testing average(a,b) function:")
    print("average(1, 2) = %g" % average(1, 2))
    # or we can even add an assert statement here
    assert average(1, 2) == 1.5
```
This “main program” will only be executed if the file training1.py is executed on its own, i.e. by pressing F5 in when training1.py is in the active window, or by calling python training1.py from the command prompt.

If the training1.py is imported as a library, using the import command, the main programme will not execute.

The testing system will import the file, and thus completely ignore the main program. (This means what you do in the main program will not conflict with the auto testing, so you can design the main program as you like to help you as you think is best.)

(In particular, the testing system will import training1.py with the command import training1 as s and for that reason the testing code refers to the functions from the file as living in the module with name s.)
More advanced suggestion

Create dedicate functions to test other functions in your code, then call these in the main program, or use a tool like py.test to do this automatically.

Return to Top