Essentials of R and JAGS coding style
I wanted to refer to Google's original style guide for R, but
is now just a few disagreements with the
Style Guide. The latter seems to be overly prescriptive
or only relevant if you are creating a package, so here's
my own "just the essentials" style guide for JAGS code
as well as R.|
Code is meant to be read by humans. "Any fool can write code that a computer can understand. Good programmers write code that humans can understand." Martin Fowler. And you should be able to run the code line by line, even if it is inside a loop or a function definition.
My only real rule is no dots in function names, as that risks confusion with R's S3 methods.
I tend to avoid dots everywhere and prefer
Names should be self-explanatory: you should not need to add a comment to explain what the object is or what the function does. (Ok, getting good, short names is difficult, so maybe a comment can help too.) Nor should you need to scroll up to find where the object was created to remind yourself what it is.
Be careful with generic names like
Avoid using the names of common R functions for your objects:
Code without spaces will work, but is unreadable! Put spaces
Exception to the last point: I often put parentheses around a whole line so that the result is displayed in the Console. Then I do put in extra spaces:
With indexing, don't put a space between the object name and
the opening "
This section looks a bit finicky, but it really really helps to make code readable, especially with nested loops (common in JAGS):
Indenting makes it easy to look down the page and see where each code block (or sub-block) begins and ends.
If your block has just one line, you can dispense with the braces, but do use a new line and indent:
Break them up. Horizontal scrolling is a pain and word-wrap doesn't understand code. The recommendation is <= 80 characters per line. Indent continuation lines by at least 2 spaces (I use 4), more if it allows pretty alignment, as in the examples below.
In a function call, put line breaks between
arguments. In calls to
In the example above, I have not put spaces around "="; that keeps function calls compact.
If you need to split a long line of algebra, put the breaks after operators, so that R or JAGS know that the line is incomplete:
At the top of the script
You probably want the script to be usable by colleagues or at least by future you. So a comment with a brief description of what it does is good. You may need to add author and copyright information, and that wretched don't-sue-me-if-it-all-goes-wrong thing.
Some folks like a comment with the date of the last update. I tend to modify files then forget to update the update date; better just look at the date stamp in File Manager.
The script should work when run in a fresh, clean R instance.
You don't need
Load all packages and data at the start of the script, so that you don't have to break off to install packages or hunt for a data file in the middle of working through the analysis.
Use blank lines, headings, and commented
I also get lost if the script is too long. (The code file for AHM1 runs to >12,000 lines!) Once you get beyond a few hundred lines it's time to look for ways of breaking it up into multiple files. If files should be run in sequence, start file names with numbers, eg, "01_data_prep.R", "02_data_explo.R", ..., "11_JAGSanalysis_augmentation.R"
|Posted 24 December 2019, last updated 10 April 2020 by Mike Meredith|