|
| 1 | +# R Project Coding Conventions for easystats |
| 2 | + |
| 3 | +This document outlines the common coding conventions observed in the `easystats` R projects. |
| 4 | + |
| 5 | +## File Naming |
| 6 | + |
| 7 | +* Files are named with `snake_case` and should correspond to the main function they contain (e.g., `check_normality.R`). |
| 8 | + |
| 9 | +## Package versioning |
| 10 | + |
| 11 | +* Package versions follow Semantic Versioning conventions. |
| 12 | + |
| 13 | +* If pull requests include user-visible changes, the "developer" version number should be increased (e.g. from 0.10.1.5 to 0.10.1.6). This ensures that `easystats::install_latest()` will download the latest versions. |
| 14 | + |
| 15 | +* For the NEWS file, the current development version should not be indicated by a version number, but rather with `(devel)`. |
| 16 | + |
| 17 | +## Code Style & Formatting |
| 18 | + |
| 19 | +* **Assignment:** Use the `<-` operator for assignment, not `=`. |
| 20 | +* **Spacing:** |
| 21 | + * Use spaces around all infix operators (`<-`, `==`, `+`, etc.). |
| 22 | + * Place a space after a comma, but not before. |
| 23 | +* **Line Length:** Keep lines to a reasonable length (e.g., under 80-100 characters) to improve readability. |
| 24 | + |
| 25 | +## Function Naming |
| 26 | + |
| 27 | +* **Public Functions:** Use lower case, underscore separated if more than one verb, i.e. `snake_case` (e.g., `check_normality()`, `model_performance()`). These functions should be exported. |
| 28 | +* **Internal Functions:** Prefix with a dot (`.`) and may use `snake_case` or `camelCase` (e.g., `.safe()`, `.get_BIC()`, `.check_normality()`). These functions should not be exported. |
| 29 | +* **Naming**: Common prefix for functions that focus on specific "tasks" or workflows (e.g. in package "insight", `get_*()` to get data, `find_*()` to find information, or in package "performance", `performance_*()` to compute measures of model quality, `check_*()` to check model assumptions...). |
| 30 | + |
| 31 | +## Argument names |
| 32 | + |
| 33 | +* Lower case, underscore separated if more than one verb. |
| 34 | +* Arguments that refer to plot or table aesthetics (like size or alpha of geoms) should follow the pattern `aesthetics_geomtype`, e.g. `size_point`, `color_line` or `alpha_rope`. |
| 35 | +* "easystats" uses the argument name `by` to indicate grouping, not `group_by` or `at`. |
| 36 | +* Use `select` and `exclude` to select columns/variables, and `keep` or `drop` to select rows/observations. |
| 37 | +* Handling NA values, especially removing missing values, is done with `remove_na`. |
| 38 | + |
| 39 | +## Element / Column names (for returned data frames) |
| 40 | + |
| 41 | +1) First letter of the column name is capital, unless (6) applies (*example:* `Parameter`). |
| 42 | +2) First letter of nouns is capital, unless (6) applies (*example:* `ROPE_Percentage`, `Prior_Scale`). |
| 43 | +3) Using underscore rather than camelCase to separate words (*example:* `CI_high`). |
| 44 | +4) Multiple words: common/main part first and adjective/specifier/variational part after, unless (8) applies (*example:* `Median_standardized`, `ROPE_percentage`). |
| 45 | +5) Abbreviations: all uppercase (*example:* `ESS`, `MCSE`, `ROPE`). |
| 46 | +6) Keep conventions for reserved words (*example:* `p`, `pd`, `Rhat`). |
| 47 | +7) Adjectives / verbs: all lower case, unless (1) applies (*example:* `high` or `low` in `CI_high` or `CI_low`). |
| 48 | +8) In case of multiple occurrences of column names that indicate the same measure or content (like `CI_low` or `SE`), the common part is appended as suffix to the context specific part (*example:* `CI_low` and `Eta2_partial_CI_low`, and **not** `CI_low` and `CI_low_Eta2_partial`). |
| 49 | +9) The "squared" term in column names that refers to "common" statistics (`Eta2`, `Chi2`, `Omega2`, ...) should be written as `2`, not `sq`, `squared` or `pétit-deux` (*example:* `Chi2`, and **not** `Chisq`, `Eta2`, and **not** `Eta_squared`). This rule does **not** apply to function names. |
| 50 | +10) Converting between "easystats" style and "broom" style can be done with `insight::standardize_names()`. |
| 51 | + |
| 52 | +## Documentation (roxygen2) |
| 53 | + |
| 54 | +All exported functions must be documented using `roxygen2`-style comments (`#'`). The documentation should include: |
| 55 | + |
| 56 | +* **Title:** A concise, one-line summary of what the function does. |
| 57 | +* **Description:** A more detailed paragraph explaining the function's purpose. |
| 58 | +* **`@param`:** A description for each function parameter. |
| 59 | +* **`@return`:** A description of the value the function returns. |
| 60 | +* **`@export`:** Tag to make the function available to users. |
| 61 | +* **`@examples` or `@examplesIf`:** Code demonstrating how to use the function. |
| 62 | +* **`@seealso`:** (Optional) Links to related functions. |
| 63 | +* **`@details`:** (Optional) Further details on the methodology or implementation. |
| 64 | + |
| 65 | +## Dependencies |
| 66 | + |
| 67 | +* Use base-R wherever possible (to reduce hard dependencies) |
| 68 | +* Make sure R-version requirements are not too strict |
| 69 | +* **Package Functions:** Always use the `::` operator to call functions from other packages (e.g., `stats::shapiro.test`, `insight::model_info`). Do not use `library()` or `require()` at the top of a file (no full import, only selective import of functions). However, in test files, package vignettes (.rmd), or in the package documentation, `::` is not required for core R packages like `stats` or `tools`. |
| 70 | +* **Conditional Checks:** Use `insight::check_if_installed("pkg_name")` to check if a package is available before using it, especially for optional ("Suggests") dependencies. |
| 71 | +* **Argument validation:** Use `insight::validate_argument()` instead of `match.arg()` to validate correct input of arguments, unless you need `several.ok`. In this case, rely on `match.arg()`. |
| 72 | + |
| 73 | +## S3 Object System |
| 74 | + |
| 75 | +* The projects make extensive use of the S3 object-oriented system. |
| 76 | +* **Generic Functions:** Define generic functions using `UseMethod("function_name")`. |
| 77 | +* **Methods:** Implement methods for specific object classes using the `function_name.class_name` naming convention (e.g., `check_normality.default`, `model_performance.lm`). |
| 78 | + |
| 79 | +## Error Handling and Messaging |
| 80 | + |
| 81 | +* Use `tryCatch` for operations that might fail. The internal `.safe()` helper is a good example. |
| 82 | +* Use the `insight` package's functions for user-facing messages: |
| 83 | + * For errors: `insight::format_error()` |
| 84 | + * For warnings: `insight::format_warning()` |
| 85 | + * For messages: `insight::format_alert()` |
| 86 | + * To highlight messages: `insight::print_color()` |
| 87 | + Note that character vectors are not pasted together, unlike in `message()`, |
| 88 | + thus you usually want to use something like `paste()` to concatenate the |
| 89 | + string. Character vectors will add a new paragraph for each string element, |
| 90 | + not paste them together. |
0 commit comments