Software Development

Owned by Tim Whitlock (Deactivated)
Last updated: Oct 13, 2023 by Joel Collins
3 min read

This page aims to describe the development process/philosophy that should be used when developing software for the UKRR. The assumption here is that the code is developed using python as the majority of the code developed in the registry is Python based. The same principles should be followed for other code bases such as UI code in Anglular, Vue etc.

Software development falls into two categories:

  • Enhancement/Bug fixes of current code base

  • New Software

In both cases the code should be part of a repository managed using git. Typically the code should be stored in the UK Kidney Association (github.com) repository.

Python code formatting

All Python code should be formatted using Black (https://github.com/psf/black) it is recommended that this be done as a pre-save function in the preferred code editor VS Code (https://code.visualstudio.com/) or a git pre-commit hook. 

Branches

Development of code should be done using branches (where ever possible) and pull requests which should be reviewed by at least two developers before merging in. If an issue is identified in the code it needs fixing not ignoring and a ticket raised before merging and deploying.

Testing

Changes to code should always be supported with tests especially if they are bug fixes. One of the reasons for this is due to the history of some of the code bases it is difficult to tell if a fix has broken some other dependency so by ensuring the right tests are in place future changes hopefully will not break earlier code.

All new code should be supported with an adequate set of tests with new tests added as issues are identified to prevent future re-occurrences. Common issues in the current code are caused by ignoring exceptions and none variables. Errors need to be handled and not just ignored. Variables need to be checked they exist and not just assumed they will be present. Given the wide variety of sources we receive data from assuming the data supplied is correct is never good. Trimming spaces and handling text when a number is expected are common issues.

All code needs to be adequately tested prior to releasing to others for testing. For the UKRDC this means the developer should test the code they develop and ensure it is working as they expect then deploy to the dev server and test with some sample dataflows. Once this has been proven successful the code should be deployed to staging where a wide range of real files can be tested and wider testing done before finally releasing to live.  

CI/CD

Ideally all codebases should use GitHub Actions for automated testing.

Deployment

Deployment of code needs to be considered and appropriate assist script s should be included in the code base as required.

Documentation

All code should be documented and should describe not only how the software should be used and deployed abut also some architectural guidance to assist someone looking at the code for the first time to understand what the code is trying to do and how it is trying to do it. Background as to how the code fits into a bigger system or why the code is required is also helpful. The aim of the documentation is to provide the information required for someone to update/correct/further develop the code as quickly and easily as possible. 

3rd Party Libraries

When using libraries for our software we should identify if the library is well maintained/tested/suited to production use. Adam Johnson has come up with a a suggestion of how this assessment could be made (https://adamj.eu/tech/2021/11/04/the-well-maintained-test/) which has been converted into a simple click app by Ryan Cheley (.https://www.ryancheley.com/2021/11/22/the-well-maintained-test)  We would do well to follow these guidelines to ensure the libraries we use are suitable.