gDR style guide

A style guide for the gdrplatform organization.

General R code

Indentation

2 spaces for indentation

Use of spaces

Always utilize if ( over if(
Always include spaces around logical comparison 1 == 1 over 1==1
Always include spaces around logical entity if (1 == 1) {} over if (1=1){}
Always include spaces around “full” subsets [ , subset] over [, subset]

Naming conventions

variables
- Utilize lower_snake_case for variables
- Assignment should use <- over =
- variable name should reflect proper tense validated_se <- validate_SE() over validate_se <- validate_SE()
function arguments
- Utilize space between function arguments function(a = "A") over function(a="A")
- Utilize lower_snake_case for function arguments function(big_matrix) over function(bigMatrix)
function names
- All action functions should start with verbs compute_metrics_SE over metrics_SE
- All internal functions start with a .
- Utilize lowerCamelCase for function names
- Function names should be short and informative
- Getters should start with get*, setters should start with set*, boolean checkers should start with is*

Functions, functions, functions

Functions definition
- Functions definition should start on the same line as function name
- Every parameter should be in separate line
- Prepare separate functions for complicated defaults (of function parameters)

 # Good
fun <- function(param1,
                param2,
                param_with_dir_for_st_important = get_st_important_dir()) {
  # Code is indented by two spaces.
  ...
}
 # Bad
fun <- function(param1, param2, param_with_dir_for_st_important = file.path(system.file(paste(param1, "SE", "rds", sep = "."), package = "important_package"))) {
  ...
}

Function assignment
- Always utilize <- over = to differentiate function arguments assignments from function assignments myFunction <- function() over myFunction = function()
Function export
- All internal functions are not exported
- All exported functions have assert tests for their parameters
vapply over sapply (or lapply + unlist() if predefining FUN.VALUE is difficult)
Do not use apply on data.frame(s) (mapply is good for row-wise operations)
Function returns
- Use implicit returns over explicit

  # Good.
  foo <- function() {
    # Do stuff.
    x
  }
  # Bad.
  foo <- function() {
    # Do stuff.
    return(x)
  }

Use of curly braces

if and else statements should be surrounded by curly braces on the same line

if (TRUE) {
  NULL
} else {
  NULL
}

## NULL

Assign simple if-else statements to a variable.

what_is_going_on <- if (is_check()) {
  flog <- "it's getting hot..."
} else if (is_mate()) {
  flog <- "Oh noooo..."
} else {
  flog <- "there is a hope..."
}

Files

Where possible, break code into smaller files
Separate each function by 2 lines
Tests should be named identically to the file in R/ (R/assays => tests/testthat/test-assays.R)

Namespacing

Only double colon namespace packages that are not imported in package.R
Common packages should all be imported in package.R
- this includes: checkmate, SummarizedExperiment, etc.

Tests

expect_equal(obs, exp) over expect_equal(exp, obs)

Miscellaneous

Exponentiation: always utilize ^ over ** for exponentiation like 2 ^ 3 over 2**3.
Numerics: place 0’s in front of decimals like 0.1 over .1
Use named indexing over positional indexing df[, "alias"] <- df[, "celllinename"] over df[, 1] <- df[, 2]
If anything is hardcoded (i.e. numbers or strings), consider refactoring by introducing additional function arguments or inserting logic over numbers.
- df[, fxn_that_returns_idx(x):length(x)] <- NA over df[, 2:length(x)] <- NA
Reassign repeated logic to a variable computed only once.

# Good.
idx <- foo()
if (length(idx) == 1) {
  f <- c(f[idx], f[-idx])
}
# Bad.
if (length(foo()) == 1) {
  f <- c(f[foo()], f[foo()])
}

General Shiny code

Do not use absolute IDs (non-namespaced IDs) inside modules. It breaks their modularity.
When adding an identifier to an element in order to style it with CSS, always prefer classes over IDs, as they work more naturally with modules and they can be reused.
Avoid inline CSS styles.
In CSS file, each rule should be on its own line.
Avoid using percentages for widths; instead, use bootstrap’s grid system by specifying columns.

General package code

Create file {pkgname}-package.R with usethis::use_package_doc()
Update {pkgname}-package.R - it should have such lines:

#' @note To learn more about functions start with `help(package = "{pkgname}")` 
#' @keywords internal
#' @return package help page
"_PACKAGE"

## [1] "_PACKAGE"

Add in the DESCRIPTION Roxygen: list(markdown = TRUE)
All constants, imports and side-effects tools should be in file package.R. Do not use zzz.R

if some functions/packages are often used within the package, add @import or @importFrom always in one place - file package.R
if using function from another package, use namespace::function_name

Executes gDRstyle specific package checks with gDRstyle::checkPackage() (use bioc_check = TRUE to verify if the requirements for Bioconductor are also met)

Git best practices

Follow Conventional Commits

Commit messages should look like <type>: <description> where type can be one of:
- fix: for bugfixes;
- feat: for new features;
- docs: for documentation changes;
- style: for formatting changes that do not affect the meaning of the code;
- test: for adding missing tests or correcting existing tests;
- refactor: for code changes that neither fixes a bug nor adds a feature
- ci: for changes to CI configuration

Any change in code should be accompanied by a bumped version.

new features - PATCH version;
bugfixes and other changes - MINOR version. Exceptions: All public packages - as to-be-released on Bioconductor have version 0.99.x.
Any changes in code should be accompanied by a bumped MINOR version regardless of the nature of the changes.

SessionInfo

sessionInfo()

## R version 4.3.0 (2023-04-21)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 22.04.3 LTS
## 
## Matrix products: default
## BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 
## LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.20.so;  LAPACK version 3.10.0
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
##  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
## 
## time zone: Etc/UTC
## tzcode source: system (glibc)
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] BiocStyle_2.30.0
## 
## loaded via a namespace (and not attached):
##  [1] vctrs_0.6.5         cli_3.6.3           knitr_1.48         
##  [4] rlang_1.1.4         xfun_0.49           stringi_1.8.4      
##  [7] purrr_1.0.2         textshaping_0.3.7   jsonlite_1.8.9     
## [10] glue_1.8.0          htmltools_0.5.7     ragg_1.2.7         
## [13] sass_0.4.8          rmarkdown_2.25      evaluate_1.0.1     
## [16] jquerylib_0.1.4     fastmap_1.2.0       yaml_2.3.10        
## [19] lifecycle_1.0.4     memoise_2.0.1       bookdown_0.37      
## [22] BiocManager_1.30.25 stringr_1.5.1       compiler_4.3.0     
## [25] fs_1.6.3            systemfonts_1.0.5   digest_0.6.37      
## [28] R6_2.5.1            magrittr_2.0.3      bslib_0.6.1        
## [31] tools_4.3.0         pkgdown_2.0.7       cachem_1.1.0       
## [34] desc_1.4.3

gDR style guide

gDR team

gDR style guide

General R code

General Shiny code

General package code

Git best practices

SessionInfo