Checklists and style guides

A pre-publication checklist covering code style, data visualisation, and accessibility — the standards I try to follow for every blogpost.
Published

February 9, 2018

Writing reproducible code is hard. Ensuring code is legible and easy to understand is another feat in itself. That’s why it’s important for folks to follow well established code style guides whether developing packages, writing single use code or even blogposts. As I insist on teaching best practices in all my training courses, it would be remiss of me not to follow my own advice when writing for this blog and elsewhere. This post has a pre-publication checklist at the bottom that I run through before publishing (or at least promoting content!), it’s split into the following sections:

Code Style Guides

In the #rstats community there’s pretty much a defacto coding standard, the code styles of RStudio which have recently been officially named the tidyverse style guide. Listing all of the myriad rules and best practices from the style guide is not only tedious it’s really difficult to apply these rules ourselves to script files that are 100+ lines of code. Thankfully there are two awesome tools developed by RStudio that help make our lives easier:

  • styler: effectively all this package does is re-indent your code files to conform to the tidyverse style guide. Install the package by running install.packages("styler") in your console. This will also install a number of Addins to RStudio that can be used to re-style files in place.

  • lintr: analyses your code for non-conformity to the tidyverse style guide and provides advice on changes you should make.

Excitingly, RStudio are currently overhauling the error messages in their packages to conform to the highly aspirational tidyverse error message style guide. Why is this exciting? Well, there’s an emphasis on providing concise human readable errors which should make it much easier to spot where and what errors are.

When I’m developing my own packages I’ll also follow these guidelines, but these are the only items I’ll add to my checklist from the tidyverse style guide:

  • Run the styler RStudio Addin on code chunks before publishing content
  • Run the lintr RStudio Addin on .Rmd files before publishing and correct all non-conformities
  • Name every single code chunk to assist in debugging
  • Where code chunks have the option include=FALSE ensure a comment is included to explain why

Data Visualisation Style Guides

I’m a co-founder of the oxshef: dataviz initiative, which promotes and supports the use of interactive visualisations for communicating research datasets and outputs. One of the core goals of the initiative is to advise researchers on the best data visualisation choice for their data, and to avoid common pitfalls in designing dataviz through our oxshef: charts site.

There are quite a few accepted wisdoms in the field of dataviz, but it’s good to take some of them with a pinch of salt:

Accessibility Style Guides

The Hugo Theme currently used by the blog is the devcows/hugo-universal-theme which is largely well designed and supports mobile devices thanks to Bootstrap. Bootstrap is a framework for building responsive web pages, content reflows as the browser window changes in size. This means a lot of work has been done for me on making the site accessible.

Pre-publication Checklist

Code Checks

  • Run the styler RStudio Addin on code chunks before publishing content
  • Run the lintr RStudio Addin on .Rmd files before publishing and correct all non-conformities

Data Viz Checks

  • Legends are sensibly ordered
  • No rainbow colour schemes

Accessibility Checks

  • Spelling and Grammar check
  • Twitter handles in Markdown links have been escaped, i.e. \[\@charliejhadley\]
  • Check all legends are sensibly ordered