Effective Computation in Physics

Chapter 19. Documentation

Computational science is a special case of scientific research: the work is easily shared via the Internet since the paper, code, and data are digital and those three aspects are all that is required to reproduce the results, given sufficient computation tools.

Victoria Stodden, “The Scientific Method in Practice: Reproducibility in the Computational Sciences”

Scientists are nomads. As students, they contribute to a piece of research for no more than four years at a time. As post-docs, their half-life on a project is even shorter. They disappear after three years, maximum. Even once they settle down as faculty or laboratory scientists, their workforce is composed primarily of these fly-by-night individuals. As such, research work in laboratories and universities occurs on a time scale rarely longer than the tenure of a typical PhD student.

In this environment, it is very common for scientists to crank out a piece of code as quickly as possible, squeeze a few publications out of it, and disappear to lands unknown. One victim in all of this is the student or researcher that follows them, seeking to extend their work. Since the first scientist working on a project valued speed over sustainability, the second researcher inherits a piece of code with no documentation. Accordingly, the original work, often termed “legacy code,” seems to be understood only by its author. The new contributors to such projects often think to themselves that rewriting the code ...