Introduction

Overview

Teaching: 10 min
Exercises: 0 min
Questions
  • Why are best practices necessary in research software?

  • How Open Source can help with better quality of software?

Objectives
  • Basics of Open Science in research software

  • Introduction to the FAIR principles

In recent years, scientific research has become more data driven and data intensive and it is no longer possible to carry out the analysis without the use of computers and research software. Unfortunately, software is not always developed following best practices that ensure its quality and sustainability. Four simple recommendations to encourage best practices in open research software is a publication that addresses this issue by providing a simple, yet robust framework of recommendations that encourage the adoption of existing best practices in research software development. These recommendations are designed around Open Science values, and provide practical suggestions that contribute to making research software and its source code more discoverable, reusable and transparent.

These recommendations recognise that not everyone can or want to make their software open from day one, but we encourage you to learn from the recommendations and adapt them to your needs. For example, you can have a private repository, you can and should still have a license, make contributions clear, and have a registry of your software.

This lesson explains the concepts behind four recommendations and teaching practical skills necessary for their implementation. The lesson is divided into four episodes, each focusing on one recommendation.

  1. Make source code publicly accessible from day one
  2. Adopt a license and comply with the license of third-party dependencies
  3. Define clear and transparent contribution, governance and communication processes
  4. Make software easy to discover by providing software metadata via a popular community registry

Open Science

When all researchers are aware of Open Science, and are trained, supported and guided at all career stages to practice Open Science, the potential is there to fundamentally change the way research is performed and disseminated. Fostering a scientific ecosystem in which research gains increased visibility, is shared more efficiently, and is performed with enhanced research integrity.Open Science Skills Working Group Report (2017)

Discussing best practices to develop research software is bound to touch on the subject of Open Science. Modern research relies on software, and building upon or reproducing that research requires access to the full source code behind that software (ref). Sharing software used for research is one of the requirements for reproducibility. In addition to reproducibility, sharing software openly allows developers/scientists to receive career credit for their efforts, either through direct citation or via published software articles.

FAIR principles

Though not all the recommendations from the FAIR data principles directly apply to software, there is a good alignment between the practices discussed here and the FAIR data principles. The FAIR principles are a set of community-developed guidelines to ensure that data or any digital object are Findable, Accessible, Interoperable and Reusable. The FAIR principles specifically emphasise enhancing the ability of machines to automatically find and use data or any digital object, and support its reuse by individuals. Standards for metadata descriptions, citation among others, are at the core of these principles (ref).

The FAIR Guiding Principles, as described in Scientific Data by Wilkinson et al:

Why best practices in research software

There are many best practices currently in place that directly aim at and are tailored for software developers. These include aspects such as test driven development and test coverage (ref), code quality (ref), continuous integration (ref), etc.

Most researchers who may need or want to develop software, do not have a formal software engineering training. This is why they might not be aware of good programming practices (e.g. code modularisation, testing, annotation, etc.) Wilson et al. 2017. However, good practices in research software development are key to generating good quality software and therefore reproducible research results.

The 4OSS recommandations provide simple guidelines to incorporate good practices in research software development and this lesson teaches how to adopt the 4OSS recommendations.

This lesson targets scientists writing research software but can also be of interest to a wider audience, particularly research funders, research institutions, journal editors, group leaders, and managers of projects producing research software.

The adoption of these recommendations offers a simple mechanism for these stakeholders to promote the development of better software and an opportunity for developers to improve and showcase their software development skills.

Starting with a couple of challenges

Challenge 1: What are the challenges of making your project open?

  • Think about the challenges of making your project open.
  • What do you need to do with your software in order to turn it into an open source project?
  • Discuss with a partner and make a list

Challenge 2: Create a project on GitHub

GitHub is a source code hosting service that facilitates collaborative software development.

  • Hello World guide describes what is GitHub and contains instructions on how to get started with GitHub.

  • You will need to created the GitHub account if you don’t have one already. If you need an account, please follow this guide.
  • Follow the Hello World guide to create a new repository on GitHub.
  • You will need to choose a name for your new repository. This is more important than you might think and you can read more on this topic in Naming and Branding Your Project guide.
  • Make sure that you’ve ticked the “Initialize this project with a README” box

Congratulations, you’ve created your first repository! This is the first step towards making your source code publicly accessible from day one.

Key Points

  • Best practices in research software are tied to the FAIR principles

  • The discussed best practices are not tailored to software developers, but rather to a wider audience