Image courtesy of John-Mark Smith. 

By Tobias Schlauch, Carina Haupt and the software engineering group at the German Aerospace Centre. 

This guide is part of the Research Software Camp: research accessibility web content series. 

Based on the "Sustainable Software Development for Researchers" alias "Bring Your Own Script and Make It Ready for Publication" workshop, this guide is a short overview about the steps recommended to make your code sustainable, enabling others to use and modify it. 

Step 1: 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 (VCS) 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.

Step 2: 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 VCS to prevent secrets like passwords or internal urls being shared. 

Step 3: 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.  

Step 4: Add a license

Without a license, potential users can’t (re-)use your software from the legal point of view. Go with common used and well-known licenses, so users know their rights and duties. If you use code from others, check its license and fulfill the respective obligations. Licenses are contracts and therefore the law applies. This is also the case for open source licenses.

Step 5: 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 automatisation 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.

Step 6: 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 (ID) for it by utilising a service like Zenodo or Software Heritage.