In DataS-DHSC/coding_principles_book: Does not matter.

Write Easy to Read Code {#easy_to_read}

(ref:easytoread-intro)

You Must - (ref:easytoread-must)

You Should - (ref:easytoread-should)

You Could - (ref:easytoread-could)

|Related Areas: | Comments
Flexible Code
Documentation | |--------------- |------------------------------------------------------------|

Style Guides {#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 |

Linters & Code Formatters {#linters}

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 |

Meaningful Names {#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.

Avoid Overlaps {#dont_overlap}

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.