Principle 2 Write Easy to Read Code
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.
You Must - Follow the DHSC adopted style for your language, use meaningful names and avoid overlaps.
You Should - Use a linter or code formatter to ensure that your code conforms to the style guide.
You Could - Review your code with colleagues to make ensure your names and style promote understanding.
| Related Areas: | Comments Flexible Code Documentation |
|---|
2.1 Style Guides
Most languages have several available style guides, which define a set of conventions to produce clean and consistently formatted code. Your style guide will define things like:
- How to use indentation and spacing
- Line length
- Naming conventions & formats
- Comment & documentation use
DHSC has adopted a single style guide for each language. Please use this style; consistency will make it easier for colleagues to understand, QA and improve your code!
| Language | DHSC Adopted Style Guide |
|---|---|
| R | tidyverse style guide |
| Python | PEP-8 |
2.2 Linters & Code Formatters
Linters are tools that you can use to ensure that you are following a given style guide. Code Formatters will take your code, and format it so that it conforms to a stanard.
| Language | DHSC Recommended Linter / Formatter |
|---|---|
| R | lintr / Styler |
| Python | pylint / Black |
2.3 Meaningful Names
Names convey meaning, naming functions & variables well can remove the need for a comment and make life easier for other readers. This includes your future self!
Find a balance: avoid meaningless names like obj or foo; but don't put an entire sentence in a variable name.
Generally, variable names should be nouns and function names should be verbs. You
Use single-letter variables only where the use or meaning is clear - such as an iterator for a loop, or where the letter represents a well-known mathematical property (think: \(e = mc^2\)).
If you find yourself attempting to cram data into variable names (e.g. model_2018, model_2019, model_2020), consider using a list or array instead.
2.4 Avoid Overlaps
When naming things be wary of overlapping with other meanings. In one context, using \(e\) for energy or \(i\) for an iterator might be sensible, but in another context might be confused with \(e\) for exponent and \(i\) for imaginary as in: \(e^{iθ} = cos(θ) + i sin(θ)\).
Be conscious of overlapping names with things which are parts of the language, or popular functions. For example in Python, you probably want to avoid common abbreviated library names (np or pd), or in R be careful about overwriting things like c which is the name of the function used to make a vector.
2.5 Name Formats
Follow your style guide and format your names consistently (i.e. using camelCase or snake_case).