Style Guides (Natty Bumpo Edition)

Software code (aka syntax) is a set of instructions for a computer. It is also a way to communicate with other people. Any language, computer or natural, enables the writer to express ideas using rules and structures. Within the confines of these rules and structures, the writer makes stylistic decisions (consciously or not). This is as true for natural languages as it is for computer code. For example, take the first three sentences from the second book from the Leatherstocking Tales by James Fenimore Cooper, published in 1826:

It was a feature peculiar to the colonial wars of North America, that the toils and dangers of the wilderness were to be encountered before the adverse hosts could meet. A wide and apparently an impervious boundary of forests severed the possessions of the hostile provinces of France and England. The hardy colonist, and the trained European who fought at his side, frequently expended months in struggling against the rapids of the streams, or in effecting the rugged passes of the mountains, in quest of an opportunity to exhibit their courage in a more martial conflict.​

This is a classic example of 19th century English literature. To modern readers, it is also a damned hard read, because of the verbose sentence structure and other stylistic choices made by the author. In the 19th century these choices were unremarkable. Today, they are anachronistic. Steven King’s next novel will be stylistically very different.

The same is true with code. How you write (and document) your code (work) matters. In the Open Source world, where we ASSUME other people will read/use our code, these style choices are regularly discussed and debated. Below, I present links to two R style guides:

• ​Google R Style Guide
• Togaware’s R Style Guide

The Google style guide is similar to th one used by the R-Core team. It is a conservative style. I prefer the T​ogaware guide over-all, because it is more stylistically progressive. That said, both present a cohesive set of expectations for programmers.

You WILL write better code/documentation if you assume someone will inevitably read your code and try to use it. Even if your work is “for your eyes only” having better written and documented code can be helpful. And if anyone ever inherits your work, they will thank you, not hate you.