(ref:easytoread-intro)
You Must - (ref:easytoread-must)
You Should - (ref:easytoread-should)
You Could - (ref:easytoread-could)
|Related Areas: | Comments
Flexible Code
Documentation |
|--------------- |------------------------------------------------------------|
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:
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 |
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 |
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.
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.
Follow your style guide and format your names consistently (i.e. using camelCase or snake_case).
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.