Shiny App – Best practice: Inline Documentation

If you are thinking: “I already know that”, these posts might be something for you as it is intended for users with pre-existing knowledge in R and Shiny. However, it assumes that you are already familiar with writing code in R, know the most widely used packages and have already built Shiny apps. With these posts, we’ll provide a framework for how to organize and optimize the development process for your Shiny apps.

In this post we’ll cover the importance of the inline documentation and also provide a hands-on example. Of course, all information can be found in our free Shiny Development Guide!

Shiny-App – Best practice: Inline Documentation

If you are thinking : “I already know that”, these posts might be something for you as it is intended for users with pre-existing knowledge in R and Shiny. However, it assumes that you are already familiar with writing code in R, know the most widely used packages and have already built Shiny apps. With these posts, we’ll provide a framework for how to organize and optimize the development process for your Shiny apps.

In this post we’ll cover the importance of the inline documentation and also provide a hands-on example. Of course, all information can be found in our free Shiny Development Guide!

Why and How?

Inline documentation covers the code of the app using inline comments. If the code is written with well thought out coding guidelines in use it is only necessary to cover a small portion of the code in this way. Inline documentation should be used for complex code chunks or code that was implemented to fix a specific problem that is not obvious afterwards. This kind of documentation allows the developers to understand why certain parts of code are implemented in the way they are and what the thought process was behind the specific code. Inline documentation should not duplicate code functionalities that are clearly obvious by writing the code.

The following example assumes that the penguins data set lies in a SQL database:

# Good

# flipper_bill_relation has to be calculated inside an additional mutate 
# because of dbplyr usage.
# Using avg_bill_length or avg_flipper_length inside the same summarize
# command they were created in to create another column would throw an error

penguins_raw %>% group_by(Species) %>% summarize(
avg_bill_length = mean(`Culmen Length (mm)`), avg_flipper_length = mean(`Flipper Length (mm)`)
) %>%
mutate(
flipper_bill_relation = avg_flipper_length / avg_bill_length - 1
) %>%
# collect first before dropping rows with NAs because drop_na can not be # translated to sql
collect() %>% drop_na()
Code language: R (r)

# Bad

# group data by Species and calculate the bill length and flipper length mean 
# as well as the relation of bill length and flipper length mean. Replace 0s 
# with NA.
penguins_raw %>% group_by(Species) %>% summarize(
avg_bill_length = mean(`Culmen Length (mm)`), avg_flipper_length = mean(`Flipper Length (mm)`)
) %>%
mutate(
flipper_bill_relation = avg_flipper_length / avg_bill_length - 1
) %>%
collect() %>% drop_na()
Code language: R (r)