Reading Code

February 10, 2012
By

(This article was first published on plausibel, and kindly contributed to R-bloggers)

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

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 his blog: plausibel.

R-bloggers.com offers daily e-mail updates about R news and tutorials on topics such as: visualization (ggplot2, Boxplots, maps, animation), programming (RStudio, Sweave, LaTeX, SQL, Eclipse, git, hadoop, Web Scraping) statistics (regression, PCA, time series, trading) and more...



If you got this far, why not subscribe for updates from the site? Choose your flavor: e-mail, twitter, RSS, or facebook...

Comments are closed.