Code Diagnostics
RStudio has the ability to perform static and dynamic analysis of R code or what is known as “Diagnostics”. Diagnostics are a way to indicate stylistic issues or errors with the code.
Enabling diagnostics
Diagnostics can be enabled and options can be set within the Global Options > Code Diagnostics editing pane:
A brief outline of the options available:
Show diagnostics for R
Toggle the display of R code diagnostics.
Enable diagnostics within R function calls
Controls whether diagnostics are performed within function calls, e.g. dplyr::select(mtcars, mpg, cyl). Toggle this if your code makes heavy use of non-standard evaluation, and RStudio is unable to produce correct diagnostics for you.
Check arguments to R function calls
Try to detect whether a particular call to a function will succeed. The diagnostics engine will report if it detects missing arguments, unmatched arguments, partially matched arguments, and too many arguments.
For example, in the code sample below, RStudio detects that the function add_numbers is missing the y argument. It is not necessary for add_numbers to exist in the current environment (i.e., within the running R session).
Similarly, missing arguments (alongside extra, or missing, commas) are reported:
Warn if variable used has no definition in scope
Warn if a symbol is used with no definition in the current, or parent, scope. The diagnostics engine will supply a suggestion if there appears to be a typo in the symbol’s name; that is, if a symbol with a similar name exists in scope as well.
Warn if variable is defined but not used
This diagnostic helps to identify if a variable is created but never used. This can be helpful when attempting to clean up old code, or in diagnosing other errors (wherein you believe a particular variable should be used, but isn’t).
In the following example, the variable result is assigned but never used or returned; instead, the sum is re-computed and then returned.
Provide R style diagnostics (e.g. whitespace)
The style diagnostic checks to see if your code conforms to Hadley Wickham’s style guide, and reports style warnings when encountered. In particular, the diagnostics engine attempts to identify inappropriate use (or lack thereof) of whitespace.
Currently, the style diagnostics feature is not user configurable; this may be addressed in an upcoming release.
Other diagnostics
Diagnostics for other languages, such as C / C++, JavaScript, and Python, are also available.
The C / C++ diagnostics engine is powered by libclang, and is able to report compiler errors and warnings inline in the source document.
Viewing diagnostics
When an error or warning is discovered, it is reported in two places:
The left gutter will show an icon related to the diagnostic’s severity
The associated diagnostic will be underlined.
Show diagnostics
These features allow you to control when diagnostics are presented and updated. Diagnostics can either be shown on save, or after a certain amount of keyboard idle time.
Project-level diagnostics
You can run the diagnostics engine over all R files in the project either using the code wizard menu, or with the keyboard shortcut Ctrl + Alt + Shift + D (Cmd + Alt + Shift + D on Mac):
After running diagnostics over the project (this may take some time), you will see the Markers pane populated with all discovered warnings and errors.
Magic comments
RStudio’s diagnostics engine can be controlled on a per-file basis by adding magic comments to the document.
The following settings are currently supported:
# !diagnostics off -- disable diagnostics within this document.
# !diagnostics style=[true/false] -- toggle style diagnostics for this document.
# !diagnostics level=[syntax/core/all] -- toggle the level, or severity, of diagnostics reported.
In addition, diagnostic warnings for particular variables can be suppressed with the suppress keyword:
# !diagnostics suppress=<comma-separated list of variables>
For example, in the below code snippet, the usage of global_variable is not reported, while the usage of other_global_variable is:
