Software Engineering Handbook
This site shares Digital Health and Care Wales' (DHCW) Software Engineering Handbook. Until now, these have only been available to internal staff.
Why have a handbook?
When you're building software, especially in healthcare, good guidance really matters. It helps everyone work in a consistent way, so the code is easier to understand, safer, and more reliable.
A handbook brings together all the important know-how: how to write clear, secure code; how to manage changes properly; how to work well across teams; and how to meet the expectations of modern software development.
It's there to help you make good decisions, avoid mistakes, and deliver software that others can trust and build on.
How this handbook is organised
The handbook is split into the following sections:
- Software Development Handbook — how to manage software development projects for DHCW.
- Using Source Control — good practice for using source control and conducting code reviews.
- Organising Your Solution — how to structure the folders and files of a software solution.
- General Coding Standards — general coding standards for software development.
- T-SQL Coding Standard — the coding standard for writing T-SQL.
- RESTful API Standards — requirements and guidance for designing and building RESTful APIs.
- Azure DevOps Handbook — how to use Azure DevOps to manage software projects.
- Software Subscriptions — how to identify, request and manage software subscriptions.
- Test Summary Report — how to write a Test Summary Report.
- Testing for Lost Updates — how to test for lost updates and other database concurrency bugs.
There's also a Coding Standard Template to use as a starting point when authoring a new coding standard.
Conventions
This section explains the conventions used throughout the handbook.
Terminology and Requirements
To be clear about what’s expected, we use specific words with defined meanings.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this handbook are to be interpreted as described in RFC 2119.
This handbook uses four consistent callout boxes:
Practical tips
Practical advice and recommendations.
Examples of good practice
Worked examples showing the standard applied correctly.
Practices to avoid
Practices that don't meet the standard.
Further reading and information
Links to further guides, information and work instructions. If a hyperlink is missing, search for the document in our Document Management System.
Exceptions to these standards
We expect you to follow these standards. Where there's a valid reason to deviate, the decision should be taken at the appropriate level and documented in a decision record, stored as described in Store ADRs in a decision records folder.
For significant technical or architectural decisions, follow the relevant DHCW governance and guidance.
Contributing
We welcome suggestions and improvements from colleagues, partners, and the wider community.
To suggest a change, please open an issue using the issue form on this repository.
Please read:
If you're unsure whether your idea is ready, open an issue anyway and a maintainer will help shape it.