Overview of Code Reuse#
This section contains a checklist of recommendations for making your software more reusable. The Detailed Recommendations for Code Reuse section contains a more in-depth explanation of each of these recommendations. You can follow the recommendations that are more suitable for your type of software and skip the ones which are not relevant in your case.
Repeatable Recommendations#
Make sure you can find it (in space; meaning: being able locate the repository/project)
Make sure you can find it (in time; meaning: being able to locate a particular version)
Make sure you can execute the same sequence of operations
Make sure your environment and sequence of operations is robust and no human is needed to replicate what was done
License your code
with a license that allows for reuse;
with a license compatible with the dependencies’ licenses
Make sure it is citable
Include necessary data
Write useful documentation*
Re-runnable Recommendations#
Remove hardcoded bits (such as paths that only existed on the hard drive where the pipeline was run) and make the code modular
Test that the modules you made can take different types of input data or parameters
Turn the modules into a package/toolbox
Write useful documentation*
Portable Recommendations#
Make sure you can recreate the environment where it lived
Write useful documentation*
Extendable Recommendations#
Write useful documentation*
Modifiable Recommendations#
Make sure your code is readable by humans
Make sure comments are present
Write useful documentation*
The observant reader might will notice that Write useful documentation
is mentioned for every level of reuse.
This is because different levels of documentation are required for different levels of reuse.
Documentation#
Different documentation requirements for different levels of reuse
Writing useful documentation is an important requirement for all levels of reuse. However, for the different levels of reuse, there are different documentation requirements:
The documentation:
explains usage, specifying:
what the software does; (required for repeatable)
how it can be used; (required for repeatable)
what options/parameters are available. (required for repeatable)
contains examples of how to run it. (required for repeatable)
has installation instructions, including good descriptions of:
the hardware it depends on (for example GPUs); (required for portable)
the operating system the software has been tested on; (required for portable)
software requirements (such as libraries and shell settings). (required for portable)