Reproducible Workflow Best Practices

You, your collaborators, or people who are interested in using your software should be able to easily access your code, understand what it does, and install it anytime.

Reusability vs reproducibility

To achieve this, you need to understand the difference between reusability and reproducibility. They are very similar concepts with common steps to achieve them. 

Reproducibility means that one should be able to get the same results by using your code and following the same steps, whereas reusability only aims to reuse the code for similar or different analysis purposes in a similar or totally different scientific field.

Best practices

No matter the scope, for both cases, you need to adopt the following best practices:

• Use a code versioning platform

Use a code versioning platform such as GitHub, GitLab, Gitea or Mercurial to monitor the code and the changes made to it. These platforms also allow you to track bugs and issues reported with your code.

• Write good documentation

Write clear and complete documentation describing your software and the steps needed to install and use it. In addition, and if relevant, you should also include an explanation of how to contribute to the code and the contact information of the owner. This is especially important if you plan to share your code with others.

• Define requirements/ environment managers/ containers

If applicable to your software, clearly list the requirements regarding the libraries, and modules used in your code. Link a version of your code to the version of the library/module needed to run it. Alternatively, you can also use environment managers such as conda and pipenv, or containers such as Docker.

• Write clean code

When writing code, you should always follow best practices for clean coding, independent of the programming language. This will allow you to easily point out and fix bugs and errors in the code, as well as to increase its comprehensibility.

• Test

If there are mistakes in the code, the results may be partly or entirely unreliable. Testing code thoroughly and frequently is vital to ensure reliable, reproducible research.

• Choose a license

In case you wish to make the software open and publish it, include an appropriate license with your code.

• Add a citation file

In case you decide to make the software open and publish it, include a citation file in the code repository. The file is used to inform the users about how they should refer to the software. For more information about citation files for research software and how to create them, watch our software citation e-learning video.