Coding Practices

Under construction

Coding

Create and share beautiful images of your source code.

https://carbon.now.sh

R

Naming

https://indrajeetpatil.github.io/second-hardest-cs-thing/

https://style.tidyverse.org/syntax.html#sec-objectnames

How good a name is can be assessed by how detailed the accompanying comment needs to be.

Good names: * Precise (but not too long) * Concise * Meaningful * Consistent * Difficult to misinterpret * Distinguishable * Searchable (i.e. updateable) * Pronounceable * Honor conventions (e.g. n for count)

Generally, variable names should be nouns and function names should be verbs.

Variable and function names should use only lowercase letters, numbers, and _.

Example of coding standards adopted in OSP organization
  • Use all ALL_CAPS for constant variables (public const double PI = 3.14;)
  • Prefix private/protected member variable with _ (private int _currentDebt)
  • Use Pascal Casing for class names (public class GlobalAccounting)
  • Use Pascal Casing for public and protected method name (public void GetRevenues())
  • Use Camel Casing for private method name (private int balanceBooks())
# not ideal - too imprecise
d

# okay - can use more precision
days

# good - middle ground
days_since_last_accident

# not ideal - unnecessarily precise
days_since_last_accident_floor_4_lab_23

...
Note

Don’t hesitate to choose lengthy names for test functions.

Unlike regular functions, long names are less problematic for test functions because

  • they are not visible or accessible to the users
  • they are not called repeatedly throughout the codebase

If you find yourself attempting to cram data into variable names (e.g. model_2018, model_2019, model_2020), consider using a list or data frame instead.

Using generic names can improve code readability, but only if language or domain customs are followed. However, even when you think you need generic names, you are better off using descriptive names.

  • In type names, avoid using class, data, object, and type (e.g. bad: classShape, good: Shape)
  • But important details should be kept (e.g. okay: child_height, better: child_height_cm)
Booleans or indicators

Boolean variable names should convey what true or false values represent. In general, use positive terms for Booleans since they are easier to process. But if the variable is only ever used in its false version (e.g. is_volcano_inactive), the negative version can be easier to work with.

Functions

Strive to use verbs for function names. Avoid using be, do, perform, etc. (e.g. bad: doAddition(), good: add())

Style

tidyverse style guide

NONMEM

  • Always MU-reference, in case EM-methods are needed.
    • Test all estimation methods.

Naming

Use descriptive variable names in snake_case or SCREAMING_SNAKE_CASE, not generic ones. Try to make them as concise as possible.

P = THETA(1) ; Don't do this
probability_no_event = THETA(1) ; Better
prob_no_event = THETA(1) ; Best

Style

Always spell out the control record in full, i.e., no abbreviations.

$COVARIANCE ; Like this
$COV ; Not like this

Always use a newline before a control record.

Always use a newline after the following control records: $PRED, $PK, $DES, $ERROR.

$PK

A = 1

$ERROR

Y = DV

Control records that can be written on a single line, or only consists of options (e.g. $ESTIMATION), does not need a newline after the control record.

$PROBLEM dummy

$INPUT ID TIME DV EVID

$PK

A = 1

$ERROR

Y = DV

$ESTIMATION METHOD=1

$COVARIANCE MATRIX=R

Separate all infix operators by spaces, except exponentials.

A = 1 + 4 - 3 * 5 / 8**3

Adding extra spaces is ok if it improves alignment of =.

Do not put spaces inside or outside parentheses for regular function calls.

; Good
LOG(A)

; Bad
LOG (A)
LOG( A )

Place a space before and after () when used with IF.

; Good
IF (A > B) THEN
  1+1
ENDIF

; Bad
IF(A > B) THEN
  1+1
ENDIF

References