From 80e217bd07aad79d8687299f4dd22e6f3fb7d59d Mon Sep 17 00:00:00 2001 From: "Hon YiWen (MLCSU)" Date: Wed, 10 Jan 2024 10:56:40 +0000 Subject: [PATCH 1/2] assorted style updates --- style/git_and_github.qmd | 2 +- style/style_guide.qmd | 38 ++++++++++++++++++++++++++++++-------- 2 files changed, 31 insertions(+), 9 deletions(-) diff --git a/style/git_and_github.qmd b/style/git_and_github.qmd index a9bde93..e526602 100644 --- a/style/git_and_github.qmd +++ b/style/git_and_github.qmd @@ -95,4 +95,4 @@ The reviewer, once happy to approve the changes, can merge the PR. ### Preparing a package release of your code -TODO +We use [semantic versioning](https://semver.org/). diff --git a/style/style_guide.qmd b/style/style_guide.qmd index 519ff2b..99b6dec 100644 --- a/style/style_guide.qmd +++ b/style/style_guide.qmd @@ -4,15 +4,37 @@ * On the whole we follow the conventions of the [tidyverse style guide](https://style.tidyverse.org/) * We prefer packages to be explicitly namespaced like this `dplyr::mutate(...)`. This is not essential in exploratory data analysis but is mandatory in all production code -* For readability please insert line breaks in your code at or before column 80. -* We prefer to avoid loading {tidyverse} because it brings in a lot of packages that are not being used. Again, not essential to follow this in exploratory data analysis but no code that is or will be deployed should ever load {tidyverse} +* We prefer to avoid loading `{tidyverse}` because it brings in a lot of packages that are not being used. Again, not essential to follow this in exploratory data analysis but no code that is or will be deployed should ever load `{tidyverse}` +* Line breaks: insert them in your code at or before column 80. -## unorganised notes +## Additional assorted notes on style 😎 -* favour `|>` over `%>%` -* favour `.qmd` over `.rmd` -* use git for *all* projects, github being the home of all of the project code +* Favour `|>` over `%>%` +* Favour `.qmd` over `.rmd` +* Use git for *all* projects, github being the home of all of the project code * RAP everything -* `{styler}` +* Use `{styler}` and `{lintr}` (or Python equivalents such as `black`) to tidy your code * https://style.tidyverse.org/ -* `{lintr}` +* Other resources: If you're not sure about something try the [NHS-R Way](https://nhsrway.nhsrcommunity.com/style-guides.html), the [UK Government accessibility guidelines](https://www.gov.uk/guidance/accessibility-requirements-for-public-sector-websites-and-apps), or the [Turing Way](https://the-turing-way.netlify.app/index.html). If you're still not sure, just ask the team. +* Line breaks in `md` files: either at 120 characters or [at sentence breaks](https://nhsrway.nhsrcommunity.com/style-guides.html#write-each-sentence-in-a-new-line-line-breaks). +* When writing about code, be explicit for {packages} by using the curly brackets and also using back ticks around \`functions()\` as these render nicely and highlight the words clearly. +* When using `dplyr`, favour one mutate over many. For example, between the two examples below, example B is preferred: + +EXAMPLE A: +``` +library(dplyr) + +starwars |> + mutate(height_cm = height) |> + mutate(name_copy = name) +``` + +EXAMPLE B: +``` +starwars |> + mutate( + height_cm = height, + name_copy = name + ) +``` + From 4146a5bf853dbcb6b312f5c4e2c8fab2cf4efed0 Mon Sep 17 00:00:00 2001 From: Matt Dray <18232097+matt-dray@users.noreply.github.com> Date: Wed, 10 Jan 2024 12:39:36 +0000 Subject: [PATCH 2/2] Correct package-name presentation, clarify sentences --- style/style_guide.qmd | 32 +++++++++++++++----------------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/style/style_guide.qmd b/style/style_guide.qmd index 99b6dec..89dfb35 100644 --- a/style/style_guide.qmd +++ b/style/style_guide.qmd @@ -2,23 +2,13 @@ ## Code style -* On the whole we follow the conventions of the [tidyverse style guide](https://style.tidyverse.org/) -* We prefer packages to be explicitly namespaced like this `dplyr::mutate(...)`. This is not essential in exploratory data analysis but is mandatory in all production code -* We prefer to avoid loading `{tidyverse}` because it brings in a lot of packages that are not being used. Again, not essential to follow this in exploratory data analysis but no code that is or will be deployed should ever load `{tidyverse}` -* Line breaks: insert them in your code at or before column 80. - -## Additional assorted notes on style 😎 - -* Favour `|>` over `%>%` -* Favour `.qmd` over `.rmd` -* Use git for *all* projects, github being the home of all of the project code -* RAP everything -* Use `{styler}` and `{lintr}` (or Python equivalents such as `black`) to tidy your code -* https://style.tidyverse.org/ -* Other resources: If you're not sure about something try the [NHS-R Way](https://nhsrway.nhsrcommunity.com/style-guides.html), the [UK Government accessibility guidelines](https://www.gov.uk/guidance/accessibility-requirements-for-public-sector-websites-and-apps), or the [Turing Way](https://the-turing-way.netlify.app/index.html). If you're still not sure, just ask the team. -* Line breaks in `md` files: either at 120 characters or [at sentence breaks](https://nhsrway.nhsrcommunity.com/style-guides.html#write-each-sentence-in-a-new-line-line-breaks). -* When writing about code, be explicit for {packages} by using the curly brackets and also using back ticks around \`functions()\` as these render nicely and highlight the words clearly. -* When using `dplyr`, favour one mutate over many. For example, between the two examples below, example B is preferred: +* In general, follow the conventions of the [tidyverse style guide](https://style.tidyverse.org/). +* Prefer packages to be explicitly namespaced with a double colon in production code, like `dplyr::mutate()`, though this is not essential in exploratory data analysis. +* Favour the base R pipe (`|>`) over the {magrittr} pipe (`%>%`). +* Avoid `library(tidyverse)` in production code because it attaches a lot of packages that might not be used, though you may use it in exploratory data analysis. +* Use {styler} and {lintr} (or Python equivalents such as `black`) to tidy your code. +* Insert linebreaks in your code at or before column 80. +* When using {dplyr}, favour one mutate over many. For example, between the two examples below, example B is preferred: EXAMPLE A: ``` @@ -38,3 +28,11 @@ starwars |> ) ``` +## Additional assorted notes on style 😎 + +* Favour Quarto (`.qmd` files) over R Markdown (`.Rmd`) for document production. +* Use Git for *all* projects and GitHub as the remote home for of all of the project code. +* Use the Reproducible Analytical Pipelines (RAP) approach wherever possible. +* Line breaks in Markdown (`.md`) files should be at 120 characters or [at sentence breaks](https://nhsrway.nhsrcommunity.com/style-guides.html#write-each-sentence-in-a-new-line-line-breaks). +* When writing about code, use curly braces to identify a {package} name and use backticks around \`functions()\` as these render nicely and highlight the words clearly. +* If you're not sure about something try the [NHS-R Way](https://nhsrway.nhsrcommunity.com/style-guides.html), the [UK Government accessibility guidelines](https://www.gov.uk/guidance/accessibility-requirements-for-public-sector-websites-and-apps), or the [Turing Way](https://the-turing-way.netlify.app/index.html). If you're still not sure, just ask the team.