Professor Carole Goble in “Better Software, Better Research”:
One of my favorite #overlyhonestmethods tweets (a hashtag for lab scientists) is Ian Holmes’s “You can download our code from the URL supplied. Good luck downloading the only postdoc who can get it to run, though.”
README: sits in top-level directory and
contains all the necessary information for installing, getting started with, and understanding the accompanying code.
May be accompanied by other specific files:
LICENSE, INSTALL, CITATION, ABOUT, CHANGELOG
SQUIRREL, version 1.2 released on 2026-09-20
# About
The Spectral Q and U Imaging Radiation Replicating Experimental Library
(SQUIRREL) is a library for replicating radiation sources with spectral details
and Q and U polarizations of superman bubblegum.
# Installation
The SQUIRREL library relies on other libraries:
- The ACORN library www.acorn.nutz
- The TREEBRANCH database format API
Install those before installing the SQUIRREL library. To install the SQUIRREL
library:
./configure
make --prefix=/install/path
make install
...
Comments provide a way to insert metainformation about code intended for people, right next to the code:
def the_function(var):
"""This is a docstring, where a function definition might live"""
a = 1 + var # this is a simple comment
return a
Also possible to pollute code with unnecessary cruft:
def decay(index, database):
# first, retrieve the decay constants from the database
mylist = database.decay_constants()
# next, try to access an element of the list
try:
d = mylist[index] # gets decay constant at index in the list
# if the index doesn't exist
except IndexError:
# throw an informative error message
raise Exception("value not found in the list")
return d
Code written cleanly will have its own voice. Use intelligent naming to make most lines of code clear without comments, then use comments sparingly to help explain reasons or complicated sections:
def decay(index, database):
lambdas = database.decay_constants()
try:
lambda_i = lambdas[index] # gets decay constant at index in the list
except IndexError:
raise Exception("value not found in the list")
return lambda
Naming: a class, variable, or function name should tell you why it exists, what it does, and how it is used.
Simple functions: functions should be small to be understandable and testable; they should only do one thing.
Consistent style: use a consistent, standardized style; e.g., select variable and function names according to the PEP8 style guide for Python.
# packages and modules are short and lowercase
packages
modules
# other objects can be long
ClassesUseCamelCase
ExceptionsAreClassesToo
functions_use_snake_case
CONSTANTS_USE_ALL_CAPS
# variable scope is *suggested* by style convention
_single_leading_underscore_ # internal to module
single_trailing_underscore_ # avoids conflicts with Python keywords
__double_leading_and_trailing__ # these are magic, like __init__
docstring: comment placed immediately after a function or class definition, typically enclosed by three pairs of double quotes:
def <name>(<args>):
"""<docstring>"""
<body>
docstrings are available within Python via help() and
iPython's magic command ?, and Sphinx picks them up.
Make docstrings descriptive and concise; you can explain the arguments of a function, its behavior, and how you intend it to be used.
def power(base, x):
"""Computes base^x. Both base and x should be integers,
floats, or another numeric type.
"""
return base**x
Sphinx can be used to automate the generation of HTML documentation; we can even use it with Travis CI to automatically build and deploy the docs on GitHub Pages.
For now, let's just make sure your docstrings are suitable for Sphinx.
def function_with_types_in_docstring(param1, param2):
"""Example function with types documented in the docstring.
`PEP 484`_ type annotations are supported. If attribute, parameter, and
return types are annotated according to `PEP 484`_, they do not need to be
included in the docstring:
Parameters
----------
param1 : int
The first parameter.
param2 : str
The second parameter.
Returns
-------
bool
True if successful, False otherwise.
.. _PEP 484:
https://www.python.org/dev/peps/pep-0484/
"""
More examples at the Sphinx documentation
def function_with_types_in_docstring(param1, param2):
"""Example function with types documented in the docstring.
`PEP 484`_ type annotations are supported. If attribute, parameter, and
return types are annotated according to `PEP 484`_, they do not need to be
included in the docstring:
Args:
param1 (int): The first parameter.
param2 (str): The second parameter.
Returns:
bool: The return value. True for success, False otherwise.
.. _PEP 484:
https://www.python.org/dev/peps/pep-0484/
"""
More examples at the Sphinx documentation
mkdir docs
cd docs
sphinx-quickstart (accept defaults if unsure; answer "yes" for question about
autodoc)
source directory holds .rst files for user guides, theory manuals, etc.
separate from the autogenerated API documentation