-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathstyle.qmd
112 lines (69 loc) · 5.82 KB
/
style.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
# Style {{< iconify fa6-solid code >}} {#sec-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.
## R
### Package styler
The [styler][] package allows you to interactively format your code according to the [tidyverse style guide][tidystyle]. 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.
### IDE and Text editor support
RStudio supports styler via the Addins drop down; see the [RStudio User Guide][rstudioguide].
Support for `styler` in other editors is provided via the [R languageserver][languageserver]:
* VSCode: [vscode-R](https://github.com/REditorSupport/vscode-R)
* Atom: [atom-ide-r](https://github.com/REditorSupport/atom-ide-r)
* Sublime Text: [R-IDE](https://github.com/REditorSupport/sublime-ide-r)
* Vim/NeoVim: [LanguageClient-neovim](https://github.com/autozimu/LanguageClient-neovim)
See the [R languageserver][languageserver] GitHub repository for more information on using the R languageserver.
### Command line/Terminal/R
In the [getwilds/makefiles repo](https://github.com/getwilds/makefiles) we have an R package Makefile template with [three make targets](https://github.com/getwilds/makefiles/blob/main/R/Makefile#L31-L40) 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.
### GitHub Actions {#sec-style-actions}
To get setup with GitHub Actions and `lintr` and `styler`, first install `lintr` if you don't have it:
```r
if (!requireNamespace("pak", quietly=TRUE)) {
install.packages("pak")
}
pak::pkg_install("lintr")
```
And then run:
```r
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](https://lintr.r-lib.org/articles/lintr.html)).
Next, run:
```r
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:
```r
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.
### 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][lintex] has all the details on exclusions.
## Python
### 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.
### IDE and Text editor support
* VSCode: [Ruff VS Code Extension](https://docs.astral.sh/ruff/integrations/#vs-code-official)
* Sublime Text: [via ruff-lsp][ruff-lsp]
* Vim/NeoVim: [via ruff-lsp](https://docs.astral.sh/ruff/integrations/#vim-neovim)
Ruff supports the Language Server Protocol via the [ruff-lsp][].
### Command line/Terminal
In the [getwilds/makefiles repo](https://github.com/getwilds/makefiles) we have a Python package Makefile template with [two make targets](https://github.com/getwilds/makefiles/blob/main/Python/Makefile#L40-L48) 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 .`).
### GitHub Actions
There's a few different options for `Ruff` for GitHub Actions. See [Ruff docs](https://docs.astral.sh/ruff/integrations/#github-actions) for details.
## Resources
Some free resources for writing better code:
- [Tidy design principles](https://design.tidyverse.org/) by Hadley Wickham
- [Software Engineering at Google](https://abseil.io/resources/swe-book) curated by Titus Winters, Tom Manshreck and Hyrum Wright
[tidystyle]: https://style.tidyverse.org/
[styler]: https://styler.r-lib.org/
[lintr]: https://lintr.r-lib.org/
[languageserver]: https://github.com/REditorSupport/languageserver
[rstudioguide]: https://docs.posit.co/ide/user/ide/guide/productivity/add-ins.html
[Ruff]: https://docs.astral.sh/ruff
[Black]: https://github.com/psf/black
[Flake8]: https://pypi.org/project/flake8/
[isort]: https://pypi.org/project/isort/
[ruff-lsp]: https://docs.astral.sh/ruff/integrations/#language-server-protocol-official
[lintex]: https://lintr.r-lib.org/articles/lintr.html#exclusions