Guides for developers

Guides for developers contain reasoning on why and information on how to make your software open and share it in order to allows others to better understand your research and potentially build on the work you have done. These contain various tips and guidance on tools and techniques on making software open, citable, robust, readable, verifiable and more widely reusable and contributable.

Building a community

  • Starting a community - taking your software to the world - Whether for research, administration, learning or teaching, software is an increasingly valuable tool and output, and needs to be managed as such. Starting a community is, of course, an important step in software sustainability. 
  • Building a better community - Building a community around software is an important step for its sustainability. An active community can become self-supporting: answering queries raised by community members and contributing new functionality and bug fixes back to your project.  
  • Choosing an open-source licence - There are so many useful resources on the web when it comes to open-source licensing that it can be confusing. This guide highlights the best resources that provide clear information about choosing a licence for software.

Open source

  • Supporting open-source software - You've written and released your open-source software, and now you've started receiving support queries. How do you support your software, handle questions and resolve bugs? Don't panic! This guide will help.
  • Choosing the right open-source software for your project - A lot of time is invested in setting up new software, and if you haven't done your homework, you could be making an expensive mistake. This guide takes you through the questions you should ask before you invest your time in new software.

Project management

  • Top tips for software developers working with researchers - Working with researchers is something the Institute has been doing for many years now. So we thought it was about time to put together our top tips for software developers working with researchers, to help foster productive, and enjoyable, collaborations.
  • Approaches to software sustainability - The way that you approach sustainability will be depend on many factors, such as the how important is the software, how mature is it, what is the size of its community and what resources available for achieving sustainability? This guide summarises the different approaches to achieving software sustainability.  
  • Before starting a new software project - Whether for research, administration, learning or teaching, software is an increasingly valuable research tool and output, and needs to be managed as such.  
  • Your project is ending. Don't panic! - To ensure valuable ideas and investment are not lost, decisions need to be made on what is to be done with the outputs from the development process. Just because you’ve finished with it now, doesn’t mean you or someone else won’t want to return to it at a later date.  
  • Sustainability and preservation framework - A key challenge in digital preservation is being able to articulate, and ideally prove, the need for preservation. A clear framework of purposes and benefits facilitates making the case for preservation.  
  • Congratulations: You've inherited some code! - This briefing paper is targeted at software developers and project managers who deal with taking over code that was developed by others, and where no proper handover has occurred.  
  • Choosing project and product names - In this guide, we'll take a look at how to choose a good name and the common pitfalls. We'll also look at searching for already used names (including trademark searches). Finally, we'll discuss our understanding of registered trademarks and passing off - two laws that can affect name choice.

Publicising software

Repositories and project infrastructure

Software development

  • Developing scientific applications using a Model-View-Controller approach - Many scientific codes in research are developed in an organic way: you need a feature, so you code a feature. It works, you understand it (and others can understand it!), and it is well tested. It's good, right? Maybe. But let's take a more thorough look...
  • Software development: general best practice - You will find that development of new code and maintenance of existing code is easier if you adopt established principles and best practices.  This guide shows you how to approach a new software development project.  
  • Ready for release? - To get people using your software as quickly and painlessly as possible, you should invest a little of your time preparing everything your users will need before you release your software. This guide describes some simple things you can do to improve your users' experience of your software.  
  • Defending your code against dependency problems - Rather than re-invent the wheel, it's a common (and good) practice to develop software that uses third-party software, but problems can occur when a new version of the code causes an incompatibility. In this guide, we describe how to choose software and develop code to avoid dependency problems.  
  • Developing maintainable software - If you want to increase the uptake of your software, make it easy to extend (and fix) and make it maintainable. This guide provides advice on the design and development of maintainable software that will benefit both you and your users.  
  • Writing readable source code - Although it ends up being processed by a machine, source code evolves within our hands. We need to ensure that we can understand what our code does and if it does this correctly, sometimes months after we wrote it. Our peers need to understand how our code works to have confidence in our research. Writing readable code costs only a fraction more time than writing unreadable code, but the payback is immense.  
  • Testing your software - Software development doesn't end when the software is written. How can you, and any developers you work with, be sure that your software meets its requirements? Does your software work as expected, and will it continue to work over its lifetime?  
  • Adopting automated testing - An example of how automated testing can be adopted for software to give researchers the security to refactor, extend, optimise or tidy, their code without the overhead of having to implement dozens of unit tests at the outset. This guide arose from our open callconsultancy projects with QuBIcTPLS and Distance.
  • How to frustrate your users, annoy other developers and please lawyers - Sometimes it's good to see a problem from a fresh perspective. We've wound up Mike Jackson into an absolute frenzy and asked him to write an anti-guide. Here's what not to do when writing software.  
  • Software evaluation guide - Assessing the quality of software - either your own or someone else's - is a tricky balance between hard objectivity and the very subjective (but very valid) individual user experience. The Institute provide a software evaluation service based on two complementary approaches developed over many years in the research software arena.  This guide explains how we go about it!
  • Using Git with shared folders and virtual machines - Virtual machines running older operating systems might not be permitted to connect to a network, and this precludes the use of off-site source code repositories. This guide provides a workaround by which the use of shared folders, between a virtual machine and its network-aware host, and Git, with its support for both local and remote usage, allows for off-site source code repositories to be used with the virtual machine.