Version 11.0

Version 11.0

CODING_STANDARDS.md

@@ -1,43 +1,50 @@
 # Visual Studio Settings
-* Identation of 3
-* Use spaces instead of tabs
-* If using Resharper, a Resharper settings file is available to format your code
+
+* Use indentation of 3.
+* Use spaces instead of tabs.
+* If using Resharper, make sure a Resharper settings file is available to format your code.
 
 # Naming Convention
-Use meaningful and understandable names. Code should read as a story and only some well known abbreviations such as DTO, PK etc. should be used
+
+Use meaningful and understandable names. Code should read as a story and only some well known abbreviations such as DTO, PK etc. should be used.
 
 ## Classes and Methods
-* Use **Pascal Casing** for class name  `public class  SomeClass`
-* Use **Pascal Casing** for public and protected method name  `public void SomeMethod()`
-* Use **Camel Casing** for private method name  ` private int somePrivateMethod()`
+
+* Use **Pascal Casing** for class name  `public class SomeClass`.
+* Use **Pascal Casing** for public and protected method name  `public void SomeMethod()`.
+* Use **Camel Casing** for private method name  ` private int somePrivateMethod()`.
 * Prefix interface with I  `public interface IMyInterface`.
-* Suffix exception classes with Exception `public class SBSuiteException: Exception`
+* Suffix exception classes with Exception `public class SBSuiteException: Exception`.
 
 ## Variables
-* Prefix private/protected member variable with _ (underscore). `private int _parentContainerId`
-* Use **ALL_CAPS Casing** for constant variables `public const double DEFAULT_PERCENTILE = 0.5;`
-* Use “Camel Casing” for local variable names and method arguments (int ingredientNode...). 
+
+* Prefix private/protected member variable with `_` (underscore): `private int _parentContainerId`.
+* Use **ALL_CAPS Casing** for constant variables: `public const double DEFAULT_PERCENTILE = 0.5;`.
+* Use **Camel Casing** for local variable names and method arguments: `int ingredientNode`.
 * All members variable should be declared at one place of a class definition.
-* Prefer variables initialization at the point of declaration.  
-* Do not use public members. Use properties instead
-* Do not use Hungarian notation (e.g. b for boolean, s for strings etc...)        
-* Except for program constants, never use global variables
+* Prefer variables initialization at the point of declaration .
+* Do not use public members. Use properties instead.
+* Do not use Hungarian notation (e.g. b for boolean, s for strings etc.).
+* Except for program constants, never use global variables.
 
 ## Comments
+
 * Do not comment the obvious
 * Indent comment at the same level of indentation as the code you are documenting
 * All comments must be written in English
-* Do not generate commments automatically
-* Do comment algorithm specifics. For example why would you start a loop at index 1 and not at 0 etc...
+* Do not generate comments automatically
+* Do comment algorithm specifics. For example, why your loop starts at index 1 and not at 0.
 * If a lot of comments are required to make a method easier to understand, break down the method in smaller methods
 * Really, do not comment the obvious
 
 # Coding Style
-* No hard coded strings and magic number should be used. Declare a constant instead 
-* Method with return values should not have side effects unless absolutely required
-* Exit early instead of having nested if statements
 
-  instead of
+* No hard coded strings and magic number should be used. Declare a constant instead.
+* Method with return values should not have side effects unless absolutely required.
+* Exit early instead of having nested if statements.
+
+  For example, instead of
+
   ```
   public void UpdateValue(bool isVisible, bool isEditable, double value)
   {
@@ -51,6 +58,7 @@ Use meaningful and understandable names. Code should read as a story and only so
   }
   ```  
   use
+
   ```
   public void UpdateValue(bool isVisible, bool isEditable, double value)
   {
@@ -60,13 +68,8 @@ Use meaningful and understandable names. Code should read as a story and only so
     _value = value;
   }
   ```
-* Do not write **if** statements in one line
-* Do not write **for** and **forEach** statements in one line
-* Always use block `{}` for **for** and **forEach** statements
-* Always have a default case for switch statement, potentially throwing an exception if the default is unreachable
-
-
-
-
-                                                    
+* Do not write `if` statements in one line.
+* Do not write `for` and `forEach` statements in one line.
+* Always use block `{}` for `for` and `forEach` statements.
+* Always have a default case for `switch` statement, potentially throwing an exception if the default is unreachable.
 

CODING_STANDARDS_R.md

@@ -2,8 +2,8 @@
 
 We will follow the <https://style.tidyverse.org/> style guide with very few changes to benefit from two R packages supporting this style guide:
 
-- [styler](http://styler.r-lib.org/)
-- [lintr](https://github.com/jimhester/lintr)
+- [`{styler}`](http://styler.r-lib.org/)
+- [`{lintr}`](https://github.com/jimhester/lintr)
 
 This coding standards will outline the more important aspects of the aforementioned style.
 
@@ -35,10 +35,9 @@ This coding standards will outline the more important aspects of the aforementio
 
 <img src="figures/blank.PNG" alt="drawing" width="300"/>
 
-
 # Naming Convention
 
-Use meaningful and understandable names. Code should read as a story and only some well known abbreviations (such as pk) should be used
+Use meaningful and understandable names. Code should read as a story and only some well known abbreviations (such as pk) should be used.
 
 ## Files
 
@@ -83,11 +82,11 @@ performSimulation <- function (...)
 DEFAULT_PERCENTILE <- 0.5
 ```
 
-- Do not use Hungarian notation (e.g., g for global, b for boolean, s for strings, etc.)
+- Do not use Hungarian notation (e.g., g for global, b for Boolean, s for strings, etc.)
 
 ## Functions
 
-Prefer using `return()` for returning result. You can rely on R to return the result of the last evaluated expression for simple functions.
+Prefer using `return()` for explicitly returning result, although you can rely on R to implicitly return the result of the last evaluated expression in a function.
 
 ## Comments
 
@@ -102,27 +101,43 @@ Prefer using `return()` for returning result. You can rely on R to return the re
 
 ## Documentation
 
-- Use roxygen comments as described [here](http://r-pkgs.had.co.nz/man.html#roxygen-comments)
+- Use roxygen comments (`#'`) as described [here](http://r-pkgs.had.co.nz/man.html#roxygen-comments).
 
-- Internal functions, if documented, should use the tag `#' @keywords internal`.
+- Do not include empty lines between the function code and its documentation.
 
-- Prefer to use `markdown` syntax to write roxygen documentation (e.g. use `**` instead of `\bold{}`).
+```r
+# Good
+#' @export
+weekend <- list("Saturday", "Sunday")
+
+# Bad
+#' @export
+
+weekend <- list("Saturday", "Sunday")
+```
+
+- Internal functions, if documented, should use the tag `#' @keywords internal`. This makes sure that package websites don't include these internal functions.
+
+- Prefer using `markdown` syntax to write roxygen documentation (e.g. use `**` instead of `\bold{}`).
 
 - To automate the conversion of existing documentation to use `markdown` syntax, install [roxygen2md](https://roxygen2md.r-lib.org/) package and run `roxygen2md::roxygen2md()` in the package root directory and carefully check the conversion.
 
 ## Conventions
 
-- Function names as code (good: `dplyr::mutate`, `mutate`, `mutate()`; bad: *mutate*, **mutate**)
+- Function names as code with parentheses (good: `dplyr::mutate()`, `mutate()`; bad: *mutate*, **mutate**)
+- Variable and (`R6`/`S3`/`S4`) object names as code (good: `x`; bad: x, *x*, **x**)
 - Package names as code with `{` (good: `{dplyr}`; bad: `dplyr`, *dplyr*, **dplyr**)
 - Programming language names as code (e.g. `markdown`, `C++`)
 
+Note that these conventions are adopted to facilitate (auto-generated) cross-linking in `{pkgdown}` websites.
+
 ### Documenting functions
 
 <http://r-pkgs.had.co.nz/man.html#man-functions>
 
 ### Documenting classes
 
-Reference classes are different across S3 and S4 because methods are associated with classes, not generics. RC also has a special convention for documenting methods: the docstring. The docstring is a string placed inside the definition of the method which briefly describes what it does. This makes documenting RC simpler than S4 because you only need one roxygen block per class.
+Reference classes are different across `S3` and `S4` because methods are associated with classes, not generics. RC also has a special convention for documenting methods: the docstring. The docstring is a string placed inside the definition of the method which briefly describes what it does. This makes documenting RC simpler than `S4` because you only need one roxygen block per class.
 
 ```r
 #' This is my Person class
@@ -156,6 +171,10 @@ Person <- R6::R6Class("Person",
 )
 ```
 
+When referring to the class property (`$name`) or method (`$set_hair()`) in package vignettes, use the `$` sign to highlight that they belong to an object. Note that the method always has parentheses to distinguish it from a property.
+
+If a class has a private method, its name should start with `.` to highlight this (e.g. `$.set_hair_color()`).
+
 # Syntax
 
 ## Spacing
@@ -172,7 +191,7 @@ Use the `styler` addin for RStudio. It will style the files for you. For more, s
 
 ### Long Lines
 
-Strive to limit your code to 80 characters per line.
+Strive to limit your code (including comments and roxygen documentation) to 80 characters per line.
 
 ### Assignments
 
@@ -182,7 +201,7 @@ Use `<-`, not `=`, for assignment.
 
 Don't put `;` at the end of a line, and don't use `;` to put multiple commands on one line.
 
-**Note:** All these styling issues, and much more, are corrected automatically with `styler`.
+**Note:** All these styling issues, and much more, are corrected automatically with `{styler}`.
 
 ### Code blocks
 
@@ -194,7 +213,7 @@ Don't put `;` at the end of a line, and don't use `;` to put multiple commands o
 
 - It is OK to drop the curly braces for very simple statements that fit on one line, **as long as they don't have side-effects**.
 
-```
+```r
 # Good
 y <- 10
 x <- if (y < 20) "Too low" else "Too high"
@@ -259,3 +278,21 @@ There is a line between text and chunk.
 
 # and the next section is separated by line as well
 ````
+
+# File naming
+
+File names containing both source code (`/R`) and tests (`/tests`) should follow the kebab-case naming convention.
+
+```r
+# bad
+DataCombined.R
+test-DataCombined.R
+
+# good
+data-combined.R
+test-data-combined.R
+```
+
+# See also
+
+A more comprehensive list of tools helpful for package development can be found in this [resource](https://github.com/IndrajeetPatil/awesome-r-pkgtools/blob/master/README.md).

GIT_WORKFLOW.md

@@ -18,7 +18,7 @@ We will use `git rebase` for all other type of code integration (sub tasks of a
 # Use Case: Implementing Task "426 it should be possible to delete observed data"
 _Note:_ A task is a cohesive unit of work. This can be part of a bigger feature or a bug fix. We assume that a fork of the repository has already been created.
 
-1. Create a `feature` branch with a **meaningful name** containing the id of the task. We will need to acquire the latest changes from the remote `develop` branch first and then create the feature branch
+1. Create a `feature` branch with a **meaningful name**, **starting with the id of the task**. We will need to acquire the latest changes from the remote `develop` branch first and then create the feature branch
   * With option  git pull -rebase = preserve
   ```
   git checkout develop