I started writing this style guide back in the 1990’s starting our with R, based on lessons from coding in COBOL, Pascal, C, C++, Python, … It has and keeps evolving over time, always with the same mantra to write your code for other humans to read and to enjoy reading. The style is now being adapted for flutter.
Data scientists write programs to ingest, manage, wrangle, visualise, analyse, report on, data in many ways, followed by training, evaluating, deploying and maintaining models. It is an art to be able to communicate our explorations and understandings as data scientists, and of course we do so through language. Whether that is a programming language or a natural language, our focus needs to be on communication and an understanding of who we are communicating to. Indeed it is this last point that is often misunderstood. We regularly find that most programmers spend most of their time reading other peoples programs and increasingly, people not trained in software engineering are reading other people’s programs. Programming languages become the means of communicating between people.
We can be as creative and differently expressive and personal in using programming languages as we are in using natural languages. Indeed, we can sometimes identify the authors of narratives written in a particular programming language, just as we might identify a Shakespearean play from a Noël Coward play.
Thus when we communicate with each other using programming languages, we must keep in mind that it truly is a mechanism for communicating to other people.
Of course our programs must be executable by computers but computers generally care little about our programs except that they be syntactically correct. So our focus should be on engaging others to read and understand the narratives we present through our programs. A badly written and presented program is not a pleasure to read. And to boot, it’s not a pleasant experience for the computer either, in the sense that where care is not taken, our narratives will more like have bugs.
Please, aim to write programs that clearly and effectively communicate the story of our data to others, no matter how short or long that program is. Think of the other. Have empathy for those who need to read what you write.
In this chapter we present simple stylistic guidelines for programming in R that support and encourage the transparency of our programs. Our programming style aims to ensure consistency and ease our understanding whilst of course also encouraging correct programs for execution by computer. Over time develop your own stylistic nuances and idiosyncrasies.
Your donation will support ongoing availability and give you access to the PDF version of this book. Desktop Survival Guides include Data Science, GNU/Linux, and MLHub. Books available on Amazon include Data Mining with Rattle and Essentials of Data Science. Popular open source software includes rattle, wajig, and mlhub. Hosted by Togaware, a pioneer of free and open source software since 1984. Copyright © 1995-2022 Graham.Williams@togaware.com Creative Commons Attribution-ShareAlike 4.0