A nice feature in python is the documentation strings (or docstrings) which provides a convenient way of associating documentation with Python modules, functions, classes, and methods.
An object’s docstring is defined by including a string constant as the first statement in the object’s definition.
def mean(dataPoints): """ This function calculates the arithmetic average of given data """
To get each function description you can use the associated “doc” method:
>>> print stats.mean.__doc__ >>> This function calculates the arithmetic average of given data
Do this for every function inside a module (here stats is the name of the file/module). Add arguments and return value descriptions.
You can also add a comment at the beginning of the file, to explain what it contains.
This and all functions descriptions can then be viewed with the help command: help(fileName)
>>> import stats >>> help(stats) Help on module stats: NAME stats - Basic statistics module for data analysis and inference DESCRIPTION This module provides functions for calculating statistics of data, including averages, variance, and standard deviation. FUNCTIONS mean(dataPoints, precision=3) the arithmetic average of given data Arguments: dataPoints: a list of data points, int or float precision (optional): digits precision after the comma, default=3 Returns: float, the mean of the input or StatsError if X is empty. median(dataPoints) the median of given data Arguments: dataPoints: a list of data points, int or float Returns: the middle number in the sorted list, a float or an int