Home

/

GitHub

/

DataS-DHSC/coding_principles_book

/

In DataS-DHSC/coding_principles_book: Does not matter.

Disclaimer {-}

This is an unapproved draft and does not represent the views of the DHSC.

Aknowledgements {-}

These principles were inspired by the MOJ Coding Principles and Standards and developed further by a group at DHSC to produce a version targeted at DHSC Analysts.

Introduction {-}

These principles are designed with the aim of improving coding standards and consistency within the department.

Adoption of these principles should improve quality, facilitate collaboration and enable effective QA of code. The principles are not language specific. This is to maximise uptake and provide a uniform set of values across languages.

The principles are designed to be achievable by all DHSC analysts producing code. Each Principle is flexible and has multiple levels:

Must - You aren't finished until your code has met this standard.
Should - Do this unless you are ready to justify not doing so.
Could - Things you can do to improve your code beyond the base standard.

Overview {-}

1) [Use Version Control]

(ref:versioncontrol-intro) Version control your code so you and your collaborators can track changes over time, trace back errors, and retrieve old versions. Version control will help you make changes and improvements to your code with confidence.

(ref:versioncontrol-must) Use version control and follow guidance on coding in the open.

(ref:versioncontrol-should) Use standard tools (Git & GitHub) to help you version control code.

(ref:versioncontrol-could) With your team, agree and design a version control workflow. Use (Git & GitHub) collaboratively and effectively.

(ref:versioncontrol-intro)

2) [Write Easy to Read Code]

(ref:easytoread-intro) Keep your code easy to read. Using a consistent style and sensible names will make it easier to collaborate and quality assure work. It will also help you spot errors.

(ref:easytoread-must) Follow the DHSC adopted style for your language, use meaningful names and avoid overlaps.

(ref:easytoread-should) Use a linter or code formatter to ensure that your code conforms to the style guide.

(ref:easytoread-could) Review your code with colleagues to make ensure your names and style promote understanding.

(ref:easytoread-intro)

3) [Correct, Clear, Fast & Concise - In That Order]

(ref:correctclearconcise-intro) Write code with your colleagues priorities in mind. They need your code to work correctly, and they will have to understand and check it before they can benefit from it being fast or concise.

(ref:correctclearconcise-must) Ensure that your code is correct and that it is clear how it functions.

(ref:correctclearconcise-should) Make your code fast and concise, where possible without sacrificing correctness, clarity or excessive resource! Record choices made to achieve this balance.

(ref:correctclearconcise-could) Use profiling tools to understand resource usage and refactor to improve clarity and performance.

(ref:correctclearconcise-intro)

4) [Write Flexible Code]

(ref:flexiblecode-intro) Write flexible code where it will save time later. Good code is often adapted and repurposed. However, don't try to solve every problem upfront, or try and cover edge cases you may never encounter. Find a balance and focus on making your code easy to change.

(ref:flexiblecode-must) Break up your code into chunks, with a clear structure and don't repeat yourself.

(ref:flexiblecode-should) Think about, and document the way your code might break with different inputs. Include input validation to catch mistakes earlier in your code and make it easier to repurpose.

(ref:flexiblecode-could) Implement and test thorough error handling. Consider writing and sharing general purposes 'tool' code, especially if you solve a problem someone else might have.

(ref:flexiblecode-intro)

5) [Comment Effectively]

(ref:comments-intro) Comment your code so that it's function is clear. Well targeted comments make it less likely that avoidable mistakes are made when using or updating your code. Colleagues and your future self will thank you.

(ref:comments-must) Write and maintain accurate comments as you code.

(ref:comments-should) Think carefully about why you are leaving comments, what to capture, and what belongs elsewhere (in documentation).

(ref:comments-could) Review old code you have written - are the comments helpful? What would you include next time?

(ref:comments-intro)

6) [Document Your Work]

(ref:documentation-intro) Maintain documentation for your code. Code is not self documenting and code without documentation won't be useful later. You need to capture higher level context such as what the code is for, why it is written a certain way and what the inputs and outputs are.

(ref:documentation-must) Produce documentation in line with Aqua book guidance.

(ref:documentation-should) Assemble documentation as you code.

(ref:documentation-could) Use document generation tools to produce documentation.

(ref:documentation-intro)

7) [Be Demonstrably Correct]

(ref:demonstrablycorrect-intro) Have a clear and robust way to demonstrate your code is correct. We need to be confident in the outputs we provide. Just because something is done with code doesn't make it immune from answering the wrong question, using the wrong inputs, or doing the calculation incorrectly.

(ref:demonstrablycorrect-must) Hold your code to the same standard as any other analysis and record evidence demonstrating it produces the right output.

(ref:demonstrablycorrect-should) Use version control to unambiguously link QA to code and outputs and construct automated tests to provide confidence that changes don't break things.

(ref:demonstrablycorrect-could) Make a fully automated reproducible analytical pipeline (RAP) which incorporates checks and validation and minimises opportunity for human error.

(ref:demonstrablycorrect-intro)

8) [Use Sensible Defaults]

(ref:sensibledefaults-intro) Do common tasks in a consistent way, following guidance. If we use the same tools and approaches across the department, it makes collaboration and quality assurance easier. This is almost always more important than using the absolute best method.

(ref:sensibledefaults-must) Be aware of the defaults, understand why we have them and follow them unless you can explain how the benefits of an alternative approach outweigh those of consistency.

(ref:sensibledefaults-should) Help define what the defaults should be, and actively participate in discussion and debate to keep them up to date and relevant.

(ref:sensibledefaults-could) Proactively review and compare the defaults used with the way you work.

(ref:sensibledefaults-intro)

9) [Be Reproducible]

(ref:reproducible-intro) Work in a way which is reproducible. Within the department, analysis is used to enable evidence based decision making. A piece of evidence which you cannot rely on being able to reproduce is not much good. There are many reproducibility pitfalls and it is our responsibility to overcome them.

(ref:reproducible-must) Keep track of what you have done and document it unambiguously so that someone else can recreate it.

(ref:reproducible-should) Write portable code, in a standard project structure so that it is easy for someone else to run it.

(ref:reproducible-could) Turn your code into a package / library / module, learn and promote RAP techniques, or use containers to achieve reproducibility.

(ref:reproducible-intro)

10) [Use Appropriate and Tidy Data]

(ref:datastructures-intro) Use the right data structures for the job. Programming languages offer many different ways to work with the same data. Using the right one will make a task easier, and decrease your chance of getting it wrong.

(ref:datastructures-must) Know what 'Tidy Data' is, and understand why it is valuable.

(ref:datastructures-should) Be familiar with the data types and structures available to you and ensure that you use the right ones.

(ref:datastructures-could) Think about relationships between datasets, design schemas and store data in an efficient way.

(ref:datastructures-intro)