Good documentation is key
In my opinion, R's documentation of functions in the {base} package is quite good. Each R documentation (.Rd) file uses the same template and includes a description of all arguments and the function's return value. This is usually supplanted with a detailed explanation of the function's purpose, practical examples, references, and notes.
Not only is the function documentation extensive, it is also easily accessible at the R console using, for example, ?transform if you want to know more about the transform function in R's {base} package.
Not all functions are good for programming
R was designed as an interactive language which means that you can explore your data interactively at the R console. For this reason, R includes many functions which are great for interactive use, but not so much for programming. These functions are typically not used in package development or even scripts which you want to be robust and reliable. The built-in R documentation doesn't elaborate much on this difference. For some functions you will find a note or a warning. The documentation for the transform function contains the following warning:
"This is a convenience function intended for use interactively. For programming it is better to use the standard subsetting arithmetic functions, and in particular the non-standard evaluation of argument 'transform' can have unanticipated consequences."
This is a helpful warning for programmers working with R and it would be nice to have this kind of context for most or all functions.
The goal of this series of articles is to pay more attention to how a function can best be used in your source code, if at all. We look at tips and tricks for dealing with typical problems which may arise and how to handle errors when they do occur. In a sense, we are taking a defensive programming approach with the goal to reduce the number of bugs in our software and to make the software easier to understand and maintain.
See the Documentation category on this site to find all functions covered in this series (so far).