Reading Code

[This article was first published on plausibel, and kindly contributed to R-bloggers]. (You can report issue about the content on this page here)
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

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


See an example here (OS Lion: rendering looks best with firefox)

To leave a comment for the author, please follow the link and comment on their blog: plausibel. offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job.
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

Never miss an update!
Subscribe to R-bloggers to receive
e-mails with the latest R posts.
(You will not see this message again.)

Click here to close (This popup will not appear again)