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.
- 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.
- 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.
- Which journals should I publish my software in? - Peer-reviewed publications are still the principal means of recording research. This guide lists the journals which accept submissions which are primarily about software.
Repositories and project infrastructure
- How continuous integration can help you regularly test and release your software - Continuous integration ensures that your software is built and tested regularly. It can help you to demonstrate that your software does what it claims to do, and that it does so correctly.
- Hosted continuous integration - A list of providers delivering hosted continuous integration to save you some of the time and effort in deploying a continuous integration server yourself.
- Help! My developer is running away! - This paper provides guidance on how to perform a technical handover, which will ensure that the soon-to-leave developer will impart his or her valuable technical knowledge and identify traps and pitfalls you should avoid.
- Getting started with Jenkins - A walkthrough of the Jenkins continuous integration server to complement our guide on Using continuous integration to build and test your software. While there are many continuous integration servers available, we like Jenkins as it is free, open source and well-established. The walkthrough forms part of our Build and test examples on GitHub.
- Getting started with Travis CI - A walkthrough of the Travis CI continuous integration service, to complement to our guides on Using continuous integration to build and test your software and Hosted continuous integration. While there are many continuous integration services available, we like Travis CI as it is free to open source projects and easy to use. The walkthrough forms part of our Build and test examples on GitHub.
- Choosing a repository for your software project - This guide provides an overview of the different options for repositories, and looks at some of the decisions you will need to make before choosing a repository
- Migrating project resources: what to remember - In this guide, we list the steps you should consider before a project migration.
- Adding schema.org to a GitHub Pages site - In this guide, we list steps you can take to improve your discoverability through search engines by adding metadata to your website.
- 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?
- An introduction to unit testing - How unit testing can help you to automatically test your software is producing correct results, using Python to illustrate, with examples.
- Scaling up unit testing using parameterisation - As our code increases in size and particularly complexity, we should expect our number of tests to increase too, which means more time writing tests. Fortunately there is something that can help with this burden which we'll look at in this guide: parameterised tests!
- 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 call consultancy projects with QuBIc, TPLS 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.