daqana’s R style guide is online

It is an enhanced version of the tidyverse style guide (http://style.tidyverse.org/).

What is a style guide and why do we need it?

A style guide provides programmers with rules specifying how their code should be written. To be functional code has to be in line with a certain grammar and punctuation. As in common language, there is some degree of freedom.

A style guide frames recommendations which restrict these freedoms with the objective of standardization. The recommendation of a certain variant can be rather arbitrary. In other cases, though, one variant may be better suited than others with respect to some quality criteria. Those quality criteria can pertain to readability and understandability, as well as to the capability (performance, scalability) of the code.

The advantages resulting from programmers following a common style guide are thus first the adherence to quality standards, second the ability to cope with code quickly even if written by others or jointly, and not least and as a consequence the easier maintainability and extensibility of the code.

Why is the tidyverse style guide used as a template and why has it been reworked?

The tidyverse comprises a lot of packages, many of them making it easy to increase the quality of one’s analyses. Those packages got extremly popular in no time. The basis for the tidyverse style guide can be found both in the “Google R style guide” (https://google.github.io/styleguide/Rguide.xml), as well as in the excellent package development book by Hadley Wickham (“R packages” http://r-pkgs.had.co.nz/).

The tidyverse style guide incorporates not only a conventional chapter on syntax but also details and How To’s for package development. It is this broad concept paired with the expertise and wide spread of the tidyverse style guide which made us consider it as a guideline for our daily tasks.

In fact, the daqana style guide coincides with the tidyverse style guide for the most part. At particular places explanations have been added to work out the decisions taken, especially where changes have been made. A note has been prepended the chapter regarding the pipe as its use is perceived rather skeptically. A short chapter on unit tests has been added.

The most visual difference is due to the introduction of colorcoding for good and bad examples, thus highly improving user friendlyness. Further, we sought to add hints to fitting lintr functions (https://github.com/jimhester/lintr) immediately in the text where rules are established. Our linters are made available in a file daqana_linters.R facilitating their use with the respective R Studio addin.

The daqana style guide is not considered as complete. We will examine how it proves of value in our daily routine and are planning extensions like a compilation of suitable styler functions (https://github.com/r-lib/styler) in analogy to the linters for upcoming versions.

So, here it is: the first version of the daqana R style guide. Happy coding! https://www.daqana.org/dqstyle-r/