PharmaSUG China 2024 Pre-conference Training

Why is Clean Code important?

Maintainability: The code is readable and understandable and has a reduced complexity, i.e., it’s easier to fix bugs
Extensibility: The architecture is simpler, cleaner, and more expressive, i.e., it’s easier to extend the capabilities and the risk of introducing bugs is reduced
Performance: The code often runs faster, uses less memory, or is easier to optimize

Example: Clean Code Rules - Step by Step

This script breaks all common clean code rules:

y=function(x){
  s1=0
  for(v1 in x){s1=s1+v1}
  m1=s1/length(x)
  i=ceiling(length(x)/2)
  if(length(x) %% 2 == 0){i=c(i,i+1)}
  s2=0
  for(v2 in i){s2=s2+x[v2]}
  m2=s2/length(i)
  c(m1,m2)
}
y(c(1:7, 100))

[1] 16.0  4.5

We now refactor it by applying clean code rules…

Example: CCR#1

y=function(x){
  s1=0
  for(v1 in x){s1=s1+v1}
  m1=s1/length(x)
  i=ceiling(length(x)/2)
  if(length(x) %% 2 == 0){i=c(i,i+1)}
  s2=0
  for(v2 in i){s2=s2+x[v2]}
  m2=s2/length(i)
  c(m1,m2)
}
y(c(1:7, 100))

[1] 16.0  4.5

CCR#1 Naming: Are the names of the variables, functions, and classes descriptive and meaningful?

Example: CCR#1

getMeanAndMedian=function(x){
    sum1=0
    for(value in x){sum1=sum1+value}
    meanValue=sum1/length(x)
    centerIndices=ceiling(length(x)/2)
    if(length(x) %% 2 == 0){
        centerIndices=c(centerIndices,centerIndices+1)
    }
    sum2=0
    for(centerIndex in centerIndices){sum2=sum2+x[centerIndex]}
    medianValue=sum2/length(centerIndices)
    c(meanValue,medianValue)
}

CCR#1 Naming

CCR#2 Formatting: Are indentation, spacing, and bracketing consistent, i.e., is the code easy to read

Example: CCR#2

getMeanAndMedian <- function(x) {
    sum1 <- 0
    for (value in x) {
        sum1 <- sum1 + value
    }
    meanValue <- sum1 / length(x)
    centerIndices <- ceiling(length(x) / 2)
    if (length(x) %% 2 == 0) {
        centerIndices <- c(
          centerIndices, centerIndices + 1)
    }
    sum2 <- 0
    for (centerIndex in centerIndices) {
        sum2 <- sum2 + x[centerIndex]
    }
    medianValue <- sum2 / length(centerIndices)
    c(meanValue, medianValue)
}

CCR#2 Formatting

CCR#3 Simplicity: Did you keep the code as simple and straightforward as possible, i.e., did you avoid unnecessary complexity

Example: CCR#3

Note:

From the Simplicity rule also follows that large source files should be split into multiple files
General guideline: keeping the number of lines to less than 1,000 lines per file can help maintain code readability and manageability

Example: CCR#3

getMeanAndMedian <- function(x) {
    meanValue <- sum(x) / length(x)
    centerIndices <- ceiling(length(x) / 2)
    if (length(x) %% 2 == 0) {
        centerIndices <- c(centerIndices, centerIndices + 1)
    }
    medianValue <- sum(x[centerIndices]) / length(centerIndices)
    c(meanValue, medianValue)
}

CCR#3 Simplicity

CCR#4 Single Responsibility Principle (SRP): Has each function a single, well-defined purpose

Example: CCR#4

getMean <- function(x) {
    sum(x) / length(x)
}

isLengthAnEvenNumber <- function(x) {
    length(x) %% 2 == 0
}

getMedian <- function(x) {
    centerIndices <- ceiling(length(x) / 2)
    if (isLengthAnEvenNumber(x)) {
        centerIndices <- c(centerIndices, centerIndices + 1)
    }
    sum(x[centerIndices]) / length(centerIndices)
}

CCR#4 Single Responsibility Principle (SRP)

CCR#5 Don’t Repeat Yourself (DRY): Did you avoid duplication of code, either by reusing existing code or creating functions

Example: CCR#5

CCR#5: DRY

Suppose you have a code block that performs the same calculation multiple times:

result1 <- 2 * 3 + 4
result2 <- 2 * 5 + 4
result3 <- 2 * 7 + 4

Create a function to encapsulate this calculation and reuse it multiple times:

calculate <- function(x) {
  2 * x + 4
}

result1 <- calculate(3)
result2 <- calculate(5)
result3 <- calculate(7)

Example: CCR#5

getMean <- function(x) {
    sum(x) / length(x)
}

isLengthAnEvenNumber <- function(x) {
    length(x) %% 2 == 0
}

getMedian <- function(x) {
    centerIndices <- ceiling(length(x) / 2)
    if (isLengthAnEvenNumber(x)) {
        centerIndices <- c(centerIndices, centerIndices + 1)
    }
    getMean(x[centerIndices])
}

CCR#5 Don’t Repeat Yourself (DRY)

CCR#6 Comments: Did you use comments to explain the purpose of code blocks and to clarify complex logic

Example: CCR#6

# returns the mean of x
getMean <- function(x) {
    sum(x) / length(x)
}

# returns TRUE if the length of x is 
# an even number; FALSE otherwise
isLengthAnEvenNumber <- function(x) {
    length(x) %% 2 == 0
}

# returns the median of x
getMedian <- function(x) {
    centerIndices <- ceiling(length(x) / 2)
    if (isLengthAnEvenNumber(x)) {
        centerIndices <- c(centerIndices, 
             centerIndices + 1)
    }
    getMean(x[centerIndices])
}

CCR#6 Comments

CCR#7 Error Handling: Did you include error handling code to gracefully handle exceptions and unexpected situations

getMean("a":"z")

Error in “a”:“z” : NA/NaN argument Additionally: Warning messages: In getMean(“a”:“z”) : NAs generated by conversion

Example: CCR#7

# returns the mean of x
getMean <- function(x) {
    tryCatch({
        sum(x) / length(x)      
    }, error = function(e) {
        stop("Failed to calculate the mean of 'x': ", e$message)
    })
}

# returns TRUE if the length of x is an even number; FALSE otherwise
isLengthAnEvenNumber <- function(x) {
    tryCatch({
        length(x) %% 2 == 0
    }, error = function(e) {
        stop("Failed to check if 'x' is an even number: ", e$message)
    })
}

# returns the median of x
getMedian <- function(x) {
    tryCatch({
        centerIndices <- ceiling(length(x) / 2)
        if (isLengthAnEvenNumber(x)) {
            centerIndices <- c(centerIndices, centerIndices + 1)
        }
        getMean(x[centerIndices])            
    }, error = function(e) {
        stop("Failed to calculate the median of 'x': ", e$message)
    })
}

CCR#7 Error Handling

Summary of Clean Code Rules

Naming: Use descriptive and meaningful names for variables, functions, and classes
Formatting: Adhere to consistent indentation, spacing, and bracketing to make the code easy to read
Simplicity: Keep the code as simple and straightforward as possible, avoiding unnecessary complexity
Single Responsibility Principle (SRP): Each function should have a single, well-defined purpose
Don’t Repeat Yourself (DRY): Avoid duplication of code, either by reusing existing code or creating functions

Summary of Clean Code Rules

Comments: Use comments to explain the purpose of code blocks and to clarify complex logic
Error Handling: Include error handling code to gracefully handle exceptions and unexpected situations
Test-Driven Development (TDD): Write tests for your code to ensure it behaves as expected and to catch bugs early
Refactoring: Regularly refactor your code to keep it clean, readable, and maintainable
Code Review: Have other team members review your code to catch potential issues and improve its quality

How to apply Clean Code Rules?

Recommended quality workflow for R packages:

Follow the naming and styling guidelines (#1, #2)
Continuously write tests and optimize the code coverage with help of tools (#7, #8)
Document the package and functions (#6)
Regularly refactor your code (#1 - #7, #9)
Publish your code on GitHub and invite colleagues to contribute (#10)

Function name	Does code…
expect_condition	fulfill a condition?
expect_equal	return the expected value?
expect_error	throw an error?
expect_false	return ‘FALSE’?
expect_gt	return a number greater than the expected value?
expect_gte	return a number greater or equal than the expected value?
expect_identical	return the expected value?
expect_invisible	return a invisible object?
expect_length	return a vector with the specified length?
expect_lt	return a number less than the expected value?
expect_lte	return a number less or equal than the expected value?
expect_mapequal	return a vector containing the expected values?
expect_message	show a message?
expect_named	return a vector with (given) names?

Function name	Does code…
expect_no_condition	run without condition?
expect_no_error	run without error?
expect_no_message	run without message?
expect_no_warning	run without warning?
expect_output	print output to the console?
expect_s3_class	return an object inheriting from the expected S3 class?
expect_s4_class	return an object inheriting from the expected S4 class?
expect_setequal	return a vector containing the expected values?
expect_silent	execute silently?
expect_true	return ‘TRUE’?
expect_type	return an object inheriting from the expected base type?
expect_vector	return a vector with the expected size and/or prototype?
expect_visible	return a visible object?
expect_warning	throw warning?

4 Ensuring Quality

Apply Clean Code Rules

Why is Clean Code important?

Example: Clean Code Rules - Step by Step

Example: CCR#1

Example: CCR#1

Example: CCR#2

Example: CCR#3

Example: CCR#3

Example: CCR#4

Example: CCR#5

Example: CCR#5

Example: CCR#6

Example: CCR#7

Summary of Clean Code Rules

Summary of Clean Code Rules

How to apply Clean Code Rules?

Package Testing

Verification vs Validation

What are Unit Tests?

Why are unit tests important?

What other important test types exist?

Testing in Practice

How to realize testing with R?

testthat Comparisons Functions (1/2)

testthat Comparisons Functions (2/2)

How to check the package quality?

How to improve the test coverage?

Example on test coverage

Example on test coverage

Example on test coverage

Code Style

Why is Code Style important?

How to optimize the code styling?

Code Styler in RStudio

Exercise

Please install the following packages before we moving on

Tasks

References

License information