Writing Good R Code and Writing Well

If you are aspiring to write good R code, you may find it helpful to occasionally spend some time reading about writing: reading about writing R code, and reading about writing about R code that you’ve written. (If you write some excellent R code, you will likely have the opportunity to write about it.)

For reading about writing good R code, a place to start might be one of the many R style guides available. Hadley Wickham includes a style guide in his Advanced R Book that is short and sweet and based on the only slightly less concise Google’s R Style Guide. Also have a look at Graham Williams Sharing R Code - With Style, a hybrid tutorial / style guide that is part of his HandsOnDataScience work in progress. In his elegant introduction, Graham writes:

Data scientists write programs to ingest, manage, wrangle, visualise, analyse and model data in many ways. It is an art to be able to communicate our explorations and understandings through a language, albeit a programming language. Of course our programs must be executable by computers but computers care little about our programs except that they be syntactically correct. Our focus should be on engaging others to read and understand the narratives we present through our programs.

Along these lines, Laurent Gatto offers his ideas on “better R programming in terms of cleaner and elegant syntax …” in his twenty-page tutorial Writing better R code.

If you are just beginning to write R functions, you may find Slawa Rokicki’s post on How to write and debug an R function or Cosma Shalizi’s write-up on Writing R Functions helpful. If you do take the trouble to work through one of these style guides, please do adhere to at least the first rule of veteran programmer Diomidis Spinellis’ 15 Rules for Writing Quality Code.

Finally, I’m for taking Graham Williams seriously: programming is an art of communication, and I believe that practicing this art may also involve occasionally writing engaging narrative about programs. Here are a few short but valuable guides to writing well. William Zinsser is the master of explaining the art of clear and unaffected writing. His 10 Writing Tips may lead you to spend some time with his book. Also worth a look are the writing tips from Morgan Ostrowsky, C.S Lakin, and the New York Times’ Amanda Christy Brown and Katherine Schulten. Three of these four writing coaches advise would-be writers to read, read widely beyond their area of expertise, and read the masters. With regard to this advice, I’ve found this short video by novelist Yaan Martel inspiring.