Enhancement: Style Guide

[mboyas-mitre]

We recommend adhering to the Tidyverse R style guide (https://style.tidyverse.org) to improve readability and consistency of code. The tidyverse style guide sums up the need for a consistent style in a particularly effective way: “Good coding style is like correct punctuation: you can manage without it, butitsuremakesthingseasiertoread.”

As the project continues to grow, particularly in an open source environment, having consistent style standards enables easy onboarding of new staff as the code can be quickly read and understood. While a specific style guide is inherently personal preference, we like the tidyverse style guide because it specifically applies to R and works with the lintR tool that can perform automated adherence checks.

Two examples where the style guide could be helpful:

https://github.com/verbal-autopsy-software/Tariff/blob/2324381cf330fc82f6022a950e7579fdee413271/Tariff/R/Tariff.r#L49 In general across the Tariff code, it appears that period separated variable names are used throughout for object names while functions are named in camelCase. However, some functions (like this one) are also named using period separation. Having a consistent naming convention will enable easy differentiation between code functionalities. Even more importantly, perhaps, the tidyverse style guide specifically recommends against using periods in names because R uses periods in other base functionality. Having periods in object/function/class names can result in confusing code such as as.data.frame.data.frame().

https://github.com/verbal-autopsy-software/Tariff/blob/2324381cf330fc82f6022a950e7579fdee413271/Tariff/R/Tariff.r#L104

Sometimes code lines can get extremely long, and having to scroll to the right adds unnecessary complexity. Limiting line length and adding line breaks can make the code significantly easier to read. The tidyverse style guide specifically recommends:

Strive to limit your code to 80 characters per line. This fits comfortably on a printed page with a reasonably sized font […] If a function call is too long to fit on a single line, use one line each for the function name, each argument, and the closing ). This makes the code easier to read and to change later.

[richardli]

Thank you for all the suggestions. I'll update and address the issues in this repo within the next few days.

[richardli]

Very good suggestions. May require more manpower than our current team capacity to clean up all styles.

@sinafala, unless you have students who would like to get into the weeds? ;)