Coding style and git

I’m attending unconf18 with an open mind and I think of myself as someone who can be quite flexible (not with my body!) and accommodating. I’m assuming that most participants at unconf18 will use = for assignment. I’m not looking to start any discussions about the different assignment operators. Simply, I am willing to use whatever the majority uses. Just like I did in my first pull request to the blogdown package (issue 263). I was trying to follow Yihui Xie’s coding style to make his life easier and have a clean (or cleaner) git history. From Yihui’s post on this pull request I can see that he liked it.

Keeping this in mind, I think that following the coding style of others will be something I’ll do at unconf18. I haven’t really worked in any R packages with many developers actively working on the package. But I imagine that setting a common coding style will minimize git conflicts, and no one wants those². I don’t know if we’ll all follow some common guidelines at unconf18. I actually imagine that it’ll be project-specific. Why? Well because you can create an R project in RStudio³ and set some defaults for the project such as:

• the number of spaces for tab
• line ending conversions

We can also set some global RStudio preferences like whether to auto-indent code after paste, length of lines.

Additionally, we can decide whether we’ll use the RStudio “wand” to reformat code.

Maybe all of this is unnecessary, maybe everyone will work in different non-overlapping functions and thus avoid git conflicts. For example, at my job sometimes I write code with = users, but we don’t work on the same lines of the code file. Later on it becomes easy to identify who wrote which line without having to use git blame (awful name, right?).

Tidyverse-like functions

So far, I think that these coding style issues are minor and will be easily dealt with. I think that we’ll all be able to adapt and instead focus on other problems (like whatever the package is trying to solve) and enjoy the experience (network, build trust as Stefanie put it).

My second concern has to do with something I imagine could require more effort: my homework before the unconf. That is, writing tidyverse-like functions. Like I’ve said, I haven’t used the R pipe %>% symbol. I’ve executed some code with it before, seeing it in many blog posts, but I’ve never actually written functions designed to be compatible with this type of logic.

If I help write a function that is not pipe-friendly, then it might not integrate nicely with other functions written by the rest of the team. It would lead to workarounds in the vignette or maybe having someone else re-factor my first function to make it pipe-friendly. Sure, I would learn from observing others make changes to my code. But I want to take advantage as much as I can from my experience at rOpenSci unconf⁴!

Since I don’t really use %>%, I’m unfamiliar with many things related to pipe-friendly (tidyverse-like) functions. For example:

• Do you document them differently? Like make a single Rd file for multiple functions. Or do you make an Rd file per function even if the example usage doesn’t involve %>%?
• I know that the first argument is important in pipe-friendly functions. But I ignore if the second and other arguments play a role or not.
• Do people use the ellipsis (...) argument in pipe-friendly functions? With my derfinder package I ended up a very deep rabbit hole using .... I explained some of the logic in my dots blog post (there are fair criticisms to going deep with ... in the comments).
• How do you write unit tests for pipe-friendly functions? Similar to how you write documentation for them, do the unit tests just test one function a time or do they test several at a time (that is the output after using %>%)?

These and other questions could involve time getting familiar with. Time that I could spend now, before unconf18, learning and at least getting a better sense of what to expect. Maybe I’m complicating myself and worrying too much about this. I imagine that the solution will involve a combination of:

• Checking some popular tidyverse packages that use %>%. Like the vignettes/README files and examples.
• Reading more about this in a book(s): I don’t know which one though.
• Playing around a bit as a user with some of these functions. See what error messages pop up: actually I don’t know how users debug a series of functions tied together via %>%.

Wrapping up

I’m not saying everyone should learn about these topics before unconf18. I think that we are all (well, maybe excluding some) worried about not knowing \(X\) or \(Y\) R/git/travis/testthat/usethis/etc topic before unconf18. And that will part of why it’ll be great to meet everyone in what is known to be an extremely welcoming R conference ^^ (seriously, check all the unconf17 posts!).

## And I'm done proofreading the post. Yay!
Sys.time()
## [1] "2018-04-27 20:24:12 EDT"

Acknowledgements

This blog post was made possible thanks to:

• BiocStyle (Oleś, Morgan, and Huber, 2018)
• blogdown (Xie, Hill, and Thomas, 2017)
• devtools (Wickham, Hester, and Chang, 2018)
• knitcitations (Boettiger, 2017)

References

[1] C. Boettiger. knitcitations: Citations for ‘Knitr’ Markdown Files. R package version 1.0.8. 2017. URL: https://CRAN.R-project.org/package=knitcitations.

[2] A. Oleś, M. Morgan and W. Huber. BiocStyle: Standard styles for vignettes and other Bioconductor documents. R package version 2.7.9. 2018. URL: https://github.com/Bioconductor/BiocStyle.

[3] H. Wickham, J. Hester and W. Chang. devtools: Tools to Make Developing R Packages Easier. R package version 1.13.5. 2018. URL: https://CRAN.R-project.org/package=devtools.

[4] Y. Xie, A. P. Hill and A. Thomas. blogdown: Creating Websites with R Markdown. ISBN 978-0815363729. Boca Raton, Florida: Chapman and Hall/CRC, 2017. URL: https://github.com/rstudio/blogdown.

Reproducibility

## Session info ----------------------------------------------------------------------------------------------------------
##  setting  value                                             
##  version  R Under development (unstable) (2017-11-29 r73789)
##  system   x86_64, darwin15.6.0                              
##  ui       X11                                               
##  language (EN)                                              
##  collate  en_US.UTF-8                                       
##  tz       America/New_York                                  
##  date     2018-04-27
## Packages --------------------------------------------------------------------------------------------------------------
##  package       * version date       source                            
##  backports       1.1.2   2017-12-13 CRAN (R 3.5.0)                    
##  base          * 3.5.0   2017-11-29 local                             
##  bibtex          0.4.2   2017-06-30 CRAN (R 3.5.0)                    
##  BiocStyle     * 2.7.9   2018-04-27 Bioconductor                      
##  blogdown        0.6     2018-04-18 CRAN (R 3.5.0)                    
##  bookdown        0.7     2018-02-18 CRAN (R 3.5.0)                    
##  colorout      * 1.1-3   2017-11-29 Github (jalvesaq/colorout@e2a175c)
##  compiler        3.5.0   2017-11-29 local                             
##  datasets      * 3.5.0   2017-11-29 local                             
##  devtools      * 1.13.5  2018-02-18 CRAN (R 3.5.0)                    
##  digest          0.6.15  2018-01-28 CRAN (R 3.5.0)                    
##  evaluate        0.10.1  2017-06-24 CRAN (R 3.5.0)                    
##  graphics      * 3.5.0   2017-11-29 local                             
##  grDevices     * 3.5.0   2017-11-29 local                             
##  htmltools       0.3.6   2017-04-28 CRAN (R 3.5.0)                    
##  httr            1.3.1   2017-08-20 CRAN (R 3.5.0)                    
##  jsonlite        1.5     2017-06-01 CRAN (R 3.5.0)                    
##  knitcitations * 1.0.8   2017-07-04 CRAN (R 3.5.0)                    
##  knitr           1.20    2018-02-20 CRAN (R 3.5.0)                    
##  lubridate       1.7.4   2018-04-11 CRAN (R 3.5.0)                    
##  magrittr        1.5     2014-11-22 CRAN (R 3.5.0)                    
##  memoise         1.1.0   2017-04-21 CRAN (R 3.5.0)                    
##  methods       * 3.5.0   2017-11-29 local                             
##  plyr            1.8.4   2016-06-08 CRAN (R 3.5.0)                    
##  R6              2.2.2   2017-06-17 CRAN (R 3.5.0)                    
##  Rcpp            0.12.16 2018-03-13 CRAN (R 3.5.0)                    
##  RefManageR      1.2.0   2018-04-25 CRAN (R 3.5.0)                    
##  rmarkdown       1.9     2018-03-01 CRAN (R 3.5.0)                    
##  rprojroot       1.3-2   2018-01-03 CRAN (R 3.5.0)                    
##  stats         * 3.5.0   2017-11-29 local                             
##  stringi         1.1.7   2018-03-12 CRAN (R 3.5.0)                    
##  stringr         1.3.0   2018-02-19 CRAN (R 3.5.0)                    
##  tools           3.5.0   2017-11-29 local                             
##  utils         * 3.5.0   2017-11-29 local                             
##  withr           2.1.2   2018-03-15 CRAN (R 3.5.0)                    
##  xfun            0.1     2018-01-22 CRAN (R 3.5.0)                    
##  xml2            1.2.0   2018-01-24 CRAN (R 3.5.0)                    
##  yaml            2.1.18  2018-03-08 CRAN (R 3.5.0)