6 min read

Coding style, coding etiquette

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. Google1.

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

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

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.

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

With fixing tools, your original source code will be modified. It is really advised to use version control with your project. If you’re nervous about getting started refer to

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 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. 😉


  1. Note that the Google R style guide inspired the tidyverse style guide but Google now refers to the tidyverse style guide as R style guide. ↩︎