Skip to content

🗺️ Good practises to create a software in the context of reproducible research

Introduction

Ensuring software reproducibility is essential for collaboration, long-term usability, and reliability. This page lists tools and best practices that we hope will help you make your software easier to share, maintain, and reuse.

What do we mean by "Software"?

See our complete definition in our glossary.

In a nutshell, "software" refers to any set of instructions executed by a computer, including scripts, applications, libraries, and research code.

Are you concerned ?

If you produce something related to the above definition of software and if your work is meant to last and not end up in the trash, then yes, certainly!

A few steps towards software reproducibility

We have organised our recommandations in five steps, to help you ensure reproductibility of your software

Managing your source code

To manage efficiently your source code files, you will need to use a control version system to track modifications and a forge to track modifications and share your work. You can read further expalnation in the card
Managing your source code files

Write clean and maintainable code

See more details in the dedicated card: Write clean and maintainable code

Managing your software environment

Managing your software envrionement is a key point for reproducibility. Often overlooked, it is a crucial element to re-built and execute your software ! The way of dealing with may depend on the langage and the execution platform. For further iinformation, see the card: Managing your software environment

Building your software

See more details in the dedicated card: Building your software

Think about your current and future users: documentation, testing, distribution ...

To encourage the use of your code, many tools are very usefull: automatic documentation, or automatic testings which ensure that any modification is safe for your code. Distribution is also a key point, since your code evolves over time and different versions may coexist.

Documentation

Many documents are necessary:

  • user manual with the main objective of the code, correponding mathematical equations for example, etc ....
  • automatic documentation from comments on your code : Sphinx, Doxygen, ...

On a forge you can use the CI pipeline to generate this last kind of documentation with the complete list of functions etc ...

Testing with CI

Continuous integration will help you to execute a list of tests at each modification of the code and control that the result is OK -> see the Gitlab documentation.

Distribute your software

In order to distribute your software, you must be able to identify a specific version. Software Heritage and HAL are made for you ! If your code is public on a forge, Software Heritage provides a unique identifier for each step of developement (SWHID), and HAL allows to cite your software ! You will also provide your software environement (see dedicated section) to allow the user to build it and run your code safely.