02-easy_to_read.Rmd

# 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](#comments) <br> [Flexible Code](#flexible_code) <br> [Documentation](#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](https://style.tidyverse.org/) |
| Python   |    [PEP-8](https://www.python.org/dev/peps/pep-0008/) |

## Linters & Code Formatters {#linters}
[Linters](https://en.wikipedia.org/wiki/Lint_%28software%29) 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](https://github.com/jimhester/lintr) / [Styler](http://styler.r-lib.org/) |
| Python   |  [pylint](https://www.pylint.org/) / [Black](https://pypi.org/project/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.

## Name Formats {#name_formats}
Follow your style guide and format your names consistently (i.e. using [camelCase](https://en.wikipedia.org/wiki/Camel_case) or [snake_case](https://en.wikipedia.org/wiki/Snake_case)).