rOpenSci (dev guide, newsletter, babeldown and babelquarto packages for multilingual publishing…)
Other package development experience, for instance contributing to pkgdown; igraph; glitter, a package to write SPARQL queries; etc. I also created saperlipopette, a package for Git training
Easy-to-read, easy-to-follow code.
Your code is executed by machines, but read by humans who will check and build upon it.
Regular spacing between elements
Not too wide
Not too long: paragraphs, existing and home-made functions
Not too stained: just the right amount of comments
😱
😌
Follow rules, always the same rules, the same rules as your friends. Example: https://style.tidyverse.org/ How do you do it?
You get used to it.
The package {styler} does it automatically! Demo.
In RStudio IDE, Ctrl+I for indentation.
No more than 80 characters per line, or something similar.
lintr can warn you! Demo
Also an RStudio setting (Code > Display > Show Margin).
As in prose, one paragraph for one idea.
Keep the main function body not too long by outsourcing things to well-named functions.
Demo!
Enter + click
Search bar
For example: modifyList()
Here’s an example: modifyList()
I used to think…
It’s pointless and boring to write, and it can even be dangerous!
One comment = like an alert!
If there are too many, we stop reading them.
Change the name of a variable rather than comment on what it is.
Change the structure of complicated code rather than comment on what it does.
Meh:
Yippee:
Possible to define a function rather than a variable, if needed.
Documenting functions with roxygen2 ;
Things you’d like to point out to a code reviewer, such as # This query can not be done via GraphQL, so have to use v3 REST API
Comments that provide a table of contents. Demo.
Even spacing between elements
Not too wide
Not too long: paragraphs, existing and home-made functions
Not too stained: just the right amount of comments
Self-explanatory names.
Logic tips: early return()
, switch()
.
Less code.
Follow fashion.
Felienne Hermans advises choosing the concepts that go into the name, the words to say it, then putting them together.
“The greater the distance between a name’s declaration and its uses, the longer the name should be” (Andrew Gerrand).
It’s clear if the person reviewing your code agrees. 😉
You can even rename existing functions if that clarifies things.
return()
Meh
return()
Better!
switch()
Meh
switch()
Better!
You can even specify a default value (or error!) for other values of the first argument.
Be strict about what scope.
Use trusted external dependencies.
Self-explanatory names.
Logic tips: return()
early, switch()
.
Less code.
Spring cleaning ;
lintr ;
Human review.
Once a year? https://www.tidyverse.org/blog/2023/06/spring-cleaning-2023/
More regularly?
Make a little improvement every time we add a new feature?
Let’s take a look at the documentation!
Read your colleagues’ code and vice versa! https://code-review.tidyverse.org/
Peer review of packages at rOpenSci https://ropensci.org/software-review/
The beauty and clarity of code are as important as its performance.
Easier to check and maintain!
Need for upkeep, maintenance.
Jenny Bryan’s talk Code Smells and Feels
Book The Art of Readable Code by Dustin Boswell and Trevor Foucher
Book Tidy Design by Hadley Wickham, in progress, with associated newsletter
To all of you and to Yani!