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:

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")
}
pak::pkg_install("lintr")

And then run:

lintr::use_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:

usethis::use_github_action("lint")

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:

usethis::use_github_action("style")

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

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: