Skip to Main Content

Research Software: Designing for Publication and Reproducibility

How to prepare scholarly code for submission to journals or repositories.


A comic with the headline "documentation," with a picture of one person lost in a dark forest and another person putting up illuminated signs that say "step 1," "step 2," and "step 3."

This image was created by Scriberia for The Turing Way community and is used under a CC-BY licence.  DOI 10.5281/zenodo.3332807.

Colleagues in your research group, reviewers, and scholarly peers will all need to know how to use your code. Another huge incentive to document your code is that, between teaching, learning, shifting your focus from one project to another, and other distractions of living life and existing in academia, you may need some reminders yourself. As the data scientist Garret Christensen advises in a piece in the edited volume The Practice of Reproducible Research:

"Comment the hell out of your code so you know what you were doing when a journal makes a decision about your submission after six months."

Below, we suggest a few methods for documentation. The level of documentation your project requires may vary. For a simple script that produces figures for a paper that you or a reviewer may wish to validate, you need to provide installation instructions, but you probably don't need to create a full-on tutorial. For a more complex project, making a Jupyter Notebook or R Notebook that combines code with notes and observations might be helpful. 

Documentation Best Practices

  • Load dependencies at the top of the program. This will help a user find, load, and troubleshoot other programs they need to run your code.
  • Name variables consistently for easier troubleshooting and to make the code more (human-)readable.
  • Comment out distinct modules and functions to clarify the purpose they serve within the code.
  • Within your code, add comments on their own line, not inline with commands. 
  • Document expected inputs and outputs--what kind of argument the program and its components expect, and what it will display or produce to indicate it has run successfully.


Tools For Documentation From Source Code

Software-Specific Styling and Commenting Guidelines