Skip to content

code formatting convention

Jump to bottom Edit New page
Dan Kelley edited this page Aug 19, 2023 · 18 revisions

Contributors are asked to adhere to the formatting conventions used in the existing code. Doing so makes it easier for others to get the gist of the code at a glance, and to find elements by using grep, etc. If you use the (excellent) https://github.com/jalvesaq/Nvim-R package for the vim editor, set both r_indent_align_args and r_indent_ess_comments to zero, set both shiftwidth and softtabstop to 4, and set expandtab on. (If you use neovim, turn lsp formatting off, using Nvim-R formatting instead.)

Documentation

All documentation is created using Roxygen2, based on the R source files in the R directory (and also the Rmd files in the vignette directory). Do not edit the files in the man directory, because your changes will be lost the next time the documentation is built.

  1. Use Title Case for function titles, except for class names (like ctd), e.g.
#' Plot a TS Diagram
#' Sample ctd Data
  1. Make sure that examples work, and that they do not use data that is external to the package. CRAN policy discourages large packages, so please do not add datasets without consulting the developers. The developers have a rule: if a new file is to be added that is N bytes long, then try to shorten another file by N bytes.
  2. For built-in datasets, use titles like
#' Sample ctd Data
  1. For built-in data files, use titles like
#' Sample ctd File
  1. Refer to functions with the [otherFunction()] syntax, which will switch the font and also create a link to the function that is referred to.

R code

  • Do not rename existing functions and variables to match your own taste.
  • Write names in camelCase, not snake_case.
  • When creating new functions and variables, follow the style of the existing code, in terms of letter case, noun-verb or verb-nown constructs, level of brevity, etc.
  • Do not end lines with space characters.
  • Do not end files with blank lines.
  • Avoid long lines (say over 120 characters).
  • Do not use <<- unless there is no practical alternative.
  • Do not define variables that you don't use.
  • Don't use T or F for variable names. And, speaking of T and F, never use them for logical values.
  • Name parameters in function calls, i.e. do not rely on parameter position.
  • Use base graphics, not ggplot().
  • Use base functions, not tidy functions.
  • Do not use magrittr pipes; use |> instead, because it is built in to R.
  • Indent with spaces, not tabs.
  • Indent in increments of 4 spaces.
  • Put the opening brace of if and for blocks on the same line as the keyword, but on a new line for a function.
  • Use your judgement in deciding whether to use braces for single-statement blocks. Clarity is the goal. If either the true or false branch is embraced, embrace both branches. Favour braces for nested blocks, because otherwise users have to count un-indents to understand program flow (AKA the python problem).
  • Do not put spaces before and after equals signs in function calls, e.g. write fcn(x=1, y=2).
  • Always put a space after a comma, as in the previous illustration and in e.g. x[i, j].
  • If you are documenting an argument that is listed in a template found in man-roxygen, try to ensure that your meaning is the same, and use the template rather than writing new text.
  • Do not add dependencies on other packages unless the developers approve of this.
  • Avoid importing functions unless necessary.
  • Document functions using Roxygen2, but do not use @export in the documentation.
  • If you add a new function, add it to NAMESPACE (see previous rule). Put it in the right spot, alphabetically.
  • Use oceDebug() to help trace the action of your code. Study the existing code for conventions.
  • In Roxygen documentation, refer to classes as e.g. [ctd-class], to functions as e.g. [fcn()], etc.
  • In Roxygen documentation, be sure that links work. The oce rule is to demote a link to a fixed-width font if the link breaks even once.
  • Indent multi-line function arguments with 4 spaces, e.g.
fcn <- function(arg1,
    arg2, ...)
  • Put the opening brace of a function on a line by itself, in the first column, e.g.
fcn <- function(arg)
{
...
}

Fortran, C and C++ code

Follow the formatting used in the code you find in the src directory. But, unless you are very well-versed in these languages, and how to hook them up with the R system, please do not try editing any of this code.

Other files

Please do not edit DESCRIPTION, NAMESPACE or any other low-level files unless you are very sure what you are doing. Minor changes can break things badely.

Always, always, always

Be sure to build, install, test and check. RStudio has tools to do this. And be sure that you have not modified the oce.Rproj file, because it has settings that are helpful, e.g. it will recreate the documentation on every build/install.

Postscript

Does it sound like you are being advised not to try editing anything in oce? Well, not really. If you have over a year of R experience, and have built packages, then you can likely edit the R code without breaking things too badly. And altering documentation should be within the scope of any user who is willing to write carefully, and to follow the existing format and writing style closely.

Quick links

Clone this wiki locally