4 Coding style and documentation

4.1 Coding style

From my experience, programmers are a weird bunch with a very individualist approach to shaping their code. Unrestrained, they can turn any programming project into a scorched-earth battlefield of formatting styles and coding conventions. To avoid this, an agreement should be made before starting the project (ideally for all future projects) on the following issues:

Code formatting. This is one of the most inflammatory topics in programming generally, and among R programmers particularly 2. First and foremost, there are no better and worse styles, but whichever formatting style has been chosen, it should be used consistently by the team.

For R, the most widespread is the formatting style proposed by Hadley Wickham and described in The tidyverse style guide. It’s based on Google’s R Style Guide. There are tools available for reformatting (formatR, styler) and validating code (lintr) according to these rules.

Code design. TBD

Code organization. TBD

4.2 Documentation

There are basically two kinds of documentation in programming projects: one should guide the end user (this might be a programmer if you’re writing a software development tool, and API or a programming library!) through your software, while the other should help the future developers understand your code. Both are equally important (for different reasons), however this chapter will focus on the latter.

Commenting code. This is the most appreciated small courtesy you can do for your (present and future) peers, and a form of art on its own. Many a programmer is tempted to describe what the commented code does – which completely missed the point of commenting the code, since it should be assumed that the developer who’s reading it is familiar with the syntax and common constructs of the programming language used (unless it’s Perl3). Instead, a good comment should explain why the commented code does what it does – so, what the author’s intention was.

Just think about it. This would be nonsense:

x = x + 1  # add 1 to x

But this can save your friends lots of head scratching in the future:

x = x + 1  # switch from 0-indexing to 1-indexing

Reference documentation. TBD

  1. To elaborate on the “<- vs =” dispute: there are virtually no differences between the two (ambiguity when using = as an assignment operator can be avoided by enclosing the expression in brackets), and none of them is “superior”. Robert Gentleman – one of the fathers of R – in his book R Programming for Bioinformatics uses = for assignments. You should keep in mind, though, that most R programmers use <- and some package repositories may reject code using =.↩

  2. Don’t get me wrong, I love Perl. Some of my best friends are Perl programmers!↩