Chapter 1 Introduction

Want to download a PDF version of this documentation? Click the PDF symbol at the top of this page:

1.1 Who is this guide for?

This guide has been compiled to support programmers within the Department for Education to write better code that facilitates QA. If you’re an experienced programmer, you shouldn’t find anything new here but if you’re a less experienced programmer and/or new to DfE, this guide should enable you to embed good code practice into your work.

This guide complements the Analytical Function Quality Assurance of Code for Analysis and Research.

It is split into several parts; chapters two to four cover the fundamentals of writing good code and maintaining a clear code structure, whilst chapters five to eight cover testing, version control and documentation and have more focus on quality assuring code. Throughout, the focus is on the R programming language but the principles mentioned in this guide are language agnostic.

1.2 Writing code for QA

There are 4 main aspects to writing high-quality code:

  1. maintaining a clear code structure
  2. testing throughout
  3. having excellent version control and
  4. providing sufficient documentation

These ways of working broadly map to 3 of the 5 pillars described by the DfE QA framework, namely Governance and Documentation, Clarity and structure and Verification. In particular, if implemented well, this guide will assist you in meeting good standards of clarity and structure and verification for the DfE QA framework.

The DfE QA framework was introduced in April 2019. The framework sets consistent standards of quality assurance across analytical work; whether data analysis, modelling, dashboard production, social research or production of Official Statistics.

1.3 Our approach to writing and updating this guidance

Our thinking has been informed by the basic principles of software development, while acknowledging that the scale of coding activity in the Department is typically small and often involves just a single individual coder. Formal software development tools are likely to be overly burdensome for many (but not all) projects, and we choose instead to use the simple three-stage framework of “design – develop – test” as our model here. Along with this goes the working rule-of-thumb that the time spent producing working code should be divided equally amongst the three stages.

The first version of this guide was written by Kester Jarvis, Niall Taylor and Remi Vergnon. It is intended to be a living document and we’d very much welcome suggestions for improvements or additions. Please contact the Modelling Improvement and Assurance Unit or raise an issue on Git. These will be reviewed by the DfE QA Working Group and any approved changes will be made.

Image from xkcd.com