Reading Code

Code Readability is maybe the most important part of producing reproducible research. If it’s impossible (i.e. very costly) for somebody else to read/understand the computer code that underlies your results, then the odds are that they will never be able or willing to reproduce and check your results. This is a big problem if we want to produce credible results. (Credible in the sense that not only you by yourself believe in what you found, just because you are the only person on earth who understands what you have done.)
If you don’t think that this is important for you, think about the possibility of collaboration with somebody else: The quality of collaboration will depend critically on your team understanding what everybody is doing.

What do we want?

We want an easy way to document computer code. Ideally, we write our documentation right into the code, as comments. This way, whenever you change your code, you change the comment and everything’s up to date.

What do we have?

There are some tools out there that help you documenting your code. R is predestined for this, as it integrates seamlessly with latex (see for example knitr or sweave). But there’s hope for everybody else out there. A nifty python script by the name of pycco does the following:

• You write your comments as usual into your source code, for example in file “src.code”
• you run “pycco src.code”  and obtain a folder ./docs containing a html file with two columns, left the comments, right the code
• it comes with mathjax support, i.e. your browser will display latex formulae.

How can I get it?

You need git. (you really do. whygitisbetterthanx.)
then get it with
git clone https://github.com/tlamadon/pycco

Example