Put your code under version control
Putting your code under version control allows you to easily go back to earlier stages as well as sharing it with others. What goes into a version control system like Git? Everything required to create a usable version of your code and to produce the intended results!
This includes the source code, documentation, build scripts, test cases, configuration files, input data, and other assets, but not files which can be generated by the user of the code.
Make sure that your code is in a sharable state
Cleaning up your code enables others to use your code and prevents you from sharing things by accident. Start by making your code usable and understandable – use common good practices recommended for your programming language and/or in your domain. Also ensure your code works not only on your machine and make dependencies transparent. Eventually, use features from your version control to prevent secrets like passwords or internal URL being shared.
Add essential documentation
If you want others to use or even contribute to your code, you need to document it. Think about your target groups (i.e., user and developer) and write down what they need to know. An outdated documentation is the enemy, so keep it short, simple, focus on what’s essential, and, very importantly, keep the documentation close to the code. A well written and structured README goes a long way.
Add a license
Without a license, potential users can’t (re-)use your software from the legal point of view. Go with commonly used and well-known licenses, so users know their rights and duties. If you use code from others, check its license and fulfil the respective obligations. Licenses are contracts and therefore the law applies. This is also the case for open-source licenses.
Mark the stable version of your code
Releases are a great way to mark stable versions of your code which can be safely used. They are also great to reference a version which produces a specific result. For a release you just need two things:
- First, ensure the code is stable. Tests can help you to gain confidence about the code’s stability. The automatization of tests makes release creation even easier.
- Second, a release number. Common release schemes not only provide an ID, but can also provide context about the release, i.e., date of release or type of change (major, minor, bug fix). An additional changelog helps to give further context.
Make your code citable
Code is often not cited today, but it is your interest to change this. Software is a research product, just like a paper or a monograph. Creating and maintaining research software is academic work and should allow for academic credit and careers. Also citing software is an important part of the provenance of research results and enables reproducibility. To enable your software to be cited, add the required metadata, and ideally create a persistent identifier (DOI) for it by utilising a service like CORA.RDR.
Source:
How to make your script ready for publication (Software Sustainability Institute). https://www.software.ac.uk/guide/how-make-your-script-ready-publication
Last updated: 20/02/2024
