2 Style
What is code style? It has to do with how you organize your code. The end goal of styling your code is that your code is more consistent. Styling code by definition has to be opinionated. You may not agree with every decision made in a style guide, but having style be done automatically for you gives you more time to think about the important decisions in your code.
If you always write code by yourself and you’re the only one that will ever look at it, that’s one thing. But that’s rarely the case, especially if you consider that yourself 6 months or 5 years from now is a user that is keenly interested in readable, consistent code. Readable, consistent code will be especially appreciated by other users and contributors.
2.1 R
2.1.1 Package styler
The styler package allows you to interactively format your code according to the tidyverse style guide. In fact, the default style used by the package is called “tidyverse” - following the style they use. That’s what WILDS packages use as it’s good enough until we’d like to tweak things.
The lintr package does automated checks of your code according to the style guide.
2.1.2 IDE and Text editor support
RStudio supports styler via the Addins drop down; see the RStudio User Guide.
Support for styler
in other editors is provided via the R languageserver:
- VSCode: vscode-R
- Atom: atom-ide-r
- Sublime Text: R-IDE
- Vim/NeoVim: LanguageClient-neovim
See the R languageserver GitHub repository for more information on using the R languageserver.
2.1.3 Command line/Terminal/R
In the getwilds/makefiles repo we have an R package Makefile template with three make targets for styling package code: lint_package
, style_file
, and style_package
. With that Makefile in the root of your package you can run lint_package
to check for any problems, and run style_file
or style_package
to fix any problems. You can also just run the R code in those make targets in a terminal or within R.
2.1.4 GitHub Actions
To get setup with GitHub Actions and lintr
and styler
, first install lintr
if you don’t have it:
if (!requireNamespace("pak", quietly=TRUE)) {
install.packages("pak")
}::pkg_install("lintr") pak
And then run:
::use_lintr() lintr
To create a configuration file for lintr
. In the file created (.lintr
) you can set custom congifuration as needed for your package (see the lintr vignette).
Next, run:
::use_github_action("lint") usethis
which creates a file .github/workflows/lint.yaml
in your package to run lintr
checks on your package. This action only reports problems and does not fix them for you. If you want to have any problems fixed automatically and committed to your main branch, run:
::use_github_action("style") usethis
Note that the above action will create commits all with the same message: "Style code (GHA)"
.
We think in most cases it makes sense to only use the lint
action and not the style
action, but you’re free to use either or both.
2.1.5 Nolint
Sometimes there are valid use cases for suppressing lint checks. For example, if there’s a rule that says line length should be no more than 80 characters, and there’s just no way to comply then you could tell lintr
to ignore that line. The lintr Getting Started article has all the details on exclusions.
2.2 Python
2.2.1 Package Ruff
There are a number of different options for styling/formatting Python code, including Black, Flake8, isort, Ruff, and more. We recommend using Ruff
as it’s extremely fast and encompasses all the things that the other tools do, and more.
2.2.2 IDE and Text editor support
- VSCode: Ruff VS Code Extension
- Sublime Text: via ruff-lsp
- Vim/NeoVim: via ruff-lsp
Ruff supports the Language Server Protocol via the ruff-lsp.
2.2.3 Command line/Terminal
In the getwilds/makefiles repo we have a Python package Makefile template with two make targets for styling package code: lint-fix
and lint-check
. With that Makefile in the root of your package you can run lint-check
to check for any problems, and lint-fix
to fix any problems. You can also just run the command line tools in a terminal (e.g., ruff check .
).
2.2.4 GitHub Actions
There’s a few different options for Ruff
for GitHub Actions. See Ruff docs for details.
2.3 Resources
Some free resources for writing better code:
- Tidy design principles by Hadley Wickham
- Software Engineering at Google curated by Titus Winters, Tom Manshreck and Hyrum Wright