In gdrplatform/gDRstyle: A package with style requirements for the gDR suite

gDR style guide

A style guide for the gdrplatform organization.

General R code

1. Indentation
2. 2 spaces for indentation
3. Use of spaces
4. Always utilize if ( over if(
5. Always include spaces around logical comparison 1 == 1 over 1==1
6. Always include spaces around logical entity if (1 == 1) {} over if (1=1){}
7. Always include spaces around "full" subsets [ , subset] over [, subset]
8. Naming conventions
9. 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()
10. 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)
11. 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*
12. Functions, functions, functions
13. 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)
  }

1. Use of curly braces
2. if and else statements should be surrounded by curly braces on the same line

if (TRUE) {
  NULL
} else {
  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..."
}

1. Files
2. Where possible, break code into smaller files
3. Separate each function by 2 lines
4. Tests should be named identically to the file in R/ (R/assays => tests/testthat/test-assays.R)
5. Namespacing
6. Only double colon namespace packages that are not imported in package.R
7. Common packages should all be imported in package.R
   • this includes: checkmate, SummarizedExperiment, etc.
8. Tests
9. expect_equal(obs, exp) over expect_equal(exp, obs)
10. Miscellaneous
11. Exponentiation: always utilize ^ over ** for exponentiation like 2 ^ 3 over 2**3.
12. Numerics: place 0's in front of decimals like 0.1 over .1
13. Use named indexing over positional indexing df[, "alias"] <- df[, "celllinename"] over df[, 1] <- df[, 2]
14. 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
15. 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

1. Do not use absolute IDs (non-namespaced IDs) inside modules. It breaks their modularity.
2. 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.
3. Avoid inline CSS styles.
4. In CSS file, each rule should be on its own line.
5. Avoid using percentages for widths; instead, use bootstrap's grid system by specifying columns.

General package code

1. Create file {pkgname}-package.R with usethis::use_package_doc()
2. 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. Add in the DESCRIPTION Roxygen: list(markdown = TRUE)
2. All constants, imports and side-effects tools should be in file package.R. Do not use zzz.R
3. if some functions/packages are often used within the package, add @import or @importFrom always in one place - file package.R
4. if using function from another package, use namespace::function_name
5. 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

1. Follow Conventional Commits
2. 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
3. Any change in code should be accompanied by a bumped version.
4. new features - PATCH version;
5. 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()

gdrplatform/gDRstyle documentation built on Sept. 6, 2024, 10:01 a.m.