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 your code, then the odds are that they will never be able to reproduce or check your results. 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 code. Ideally, we write our documentation right into the source 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

---

---

Tags: Economics, R