Do you indent your code with one tab, two spaces, or eight spaces? Do you feel strongly about the location of the curly brace closing a function definition? Do you have naming preferences? You probably have picked up some habits along the way. In any case, having some sort of consistency in coding style will help those who read the code to understand, fix or enhance it. In this post, we shall share some resources about coding style, useful tools, and some remarks on etiquette.

What is coding style?

Coding style is a set of rules about well, aesthetics (aligning and code spacing) but also naming (of variables, functions, etc.), commenting, structuring (e.g. avoiding complex logic), etc. These rules help with better code clarity and collaboration.

Sometimes some rules are enforced by the language (indentation in Python), sometimes the language is quite loose, like… R where you can add a lot of spaces, and so in that case more style guides exist.

Coding style has an universal goal: making your code easier to understand and maintain, for you later and for your code collaborator. Having a team/company style guide is common practice. Major Tech Companies have style guides, e.g. Google¹.

However there is no “right” coding style as the “correct” choice depends on personal preferences, and the constraints at hand.

Resources

One way to develop a sense of coding style is to read a lot of code, but where to learn about coding style explicitly?

Specific R resources

The most popular, or at least most documented style guide out there is the tidyverse style guide.

Some other style preferences include

• Mark Padgham’s spacing preferences;
• Roger Peng’s 8-space indentations;
• Yihui Xie’s preference for equal sign assignments (as presented in this issue comment);
• Google R Style guide, a fork of Tidyverse style guide but with variations e.g. a preference for BigCamelCase for function names.
• The style guide of the mlr organization (for machine learning in R).
• Your own preferences? Yes it’s fine to have some as long as your team agrees. 😉 Feel free to mention your preferences in the comments. This is a non-judgmental space (or indent 😁).

Most style guides will have some preferences regarding code spacing, or “breathing”.

Someone in #rstats Twitter said “let your code breathe” regarding spacing and it’s been my mantra to my coworkers.

Thank you to the person who’s handle I don’t remember

— jos (@JosiahParry) March 17, 2022

Even though RStudio existed, I wrote all my code for that class in Notepad and copied it into the R GUI to run. Also had not yet learned how to let my code b r e a t h e.

— Kara Woo (@kara_woo) January 26, 2022

Another excellent resource is Jenny Bryan’s useR! 2018 keynote “Code Smells and Feels”. It’s more focused on code structure and commenting.

General resources

The resources listed below are books without a free version online. Hopefully libraries and used book stores can help.

How I relax on the beach: programming book (the art of readable code, highly recommended) and cocktail (paloma, also highly recommended) pic.twitter.com/XY2LuRUl90

— Hadley Wickham (@hadleywickham) January 10, 2018

• The Art of Readable Code by Dustin Boswell, Trevor Foucher can be (even for those who do not view it as a beach read 🍸), a short, light and actionable read.

• Refactoring by Martin Fowler is an inspiration for the aforementioned keynote talk by Jenny Bryan. It defines code smells and refactoring techniques. See also the blog post “Explaining Variable” by Pete Hodgson (heard of via Jenny Bryan).

• The Programmer’s Brain by Felienne Hermans gives a perspective on e.g. how code smells or bad naming influence cognitive load. It is full of practical tips.

Tools

To begin with the most important, or basic, tool here is probably to use an IDE, integrated development environment, like RStudio IDE or VSCODE, as IDEs come with, or easily support, code diagnostic tools.

Diagnostic tools

lintr

Linting tools will indicate errors and potentially style preference violations.

The lintr R package by Jim Hester has a lot of useful linters such as whether code is commented, whether lines are too long etc.

It is pretty common to find linting tools in all editors (VSCODE and others) and for most languages. To set up lintr with your code editor refer to its docs. Unless you have RStudio IDE and linting is the one included already in the IDE (for errors mainly only, not style preference). If you use VSCODE, vscode-R extension includes diagnostic tool – see https://github.com/REditorSupport/vscode-R/wiki/R-Language-Service#diagnostics.

Some teams likes to run diagnostic tools as part of their Continuous Integration (CI) workflow. lintr can be used in this context as part of tests suits with testthat – see expect_lint()

pkgcheck

One of the aspects checked by rOpenSci Mark Padgham’s pkgcheck package is “Left-assign operators must be used consistently throughout all code (so either all = or all <-, but not a mixture of both).".

Fixing tools

RStudio IDE shortcut for code indentation

In RStudio IDE selecting code and hitting Ctrl + I will re-indent code for you!

styler

The styler R package automatically re-formats code. Its documentation includes a handy vignette on customizing styler, for when preferences differ from the default. Examples:

• the tiny spaceout R package that adds spaces between code references.
• the grkstyle R package holding Garrick Aden-Buie’s personal preferences.
• the styler.mlr R package implementing the mlr style guide.

The styler package documents some third-part integration: you don’t have to remember to run styler manually. In particular, to use styler on its own CI workflow on GitHub Actions: https://github.com/r-lib/actions/tree/v2-branch/examples#style-package

formatr R package

The formatr R package formats R code automatically too, but with less customization possibilities.

For more tools helping with code improvements, refer to the R-hub blog post “Workflow automation tools for package developers” including tips on when to use such tools.

Other languages

For Python there’s black.

A special note on ( R ) Markdown styling

When writing this post in Markdown we hit return after each sentence or even more regularly. This does not influence how the resulting post looks like but it makes reviewing easier as GitHub PR comments and change suggestions are by line! See more rationale about this.

The new Visual Editor in RStudio is a way to enforce a common style in Markdown file. It can be configured, e.g. regarding one line per sentence, so the the IDE automatically modifies source files which insure in collaboration than everyone will write the same.

The tools for styling in R can be used in R Markdown document thanks to knitr format option which support formatR and styler.

Etiquette

If you are a contributor to a codebase, you’ll probably have to adapt your style to the maintainer’s or maintainers’ preferences. These preferences might be implicit (seen by reading existing code) or explicit (in a contributing guide). Now, depending on your relation to the maintainers (e.g. is it your first contribution), you might start a discussion about changing some of the conventions, perhaps changing their mind or reaching a compromise (assigning with =, but with spaces before and after each equal sign).

If you are the maintainer of a codebase, you’ll need to be forgiving when stating your preferences and explaining how to implement them; or you might even want to take matters in your own hands and do some restyling yourself.

Conclusion

In this post we shared documentation of and tooling for coding style. We hope it can help you write or advocate for more readable code. Practice makes perfect, so go forth and participate in code production and reviews. 😉