Shiny-App – Best practice: Inline Documentation

Wenn Sie jetzt denken: „Das weiß ich schon“, dann könnte dieser Beitrag etwas für Sie sein, denn er richtet sich an AnwenderInnen mit Vorkenntnissen in R und Shiny. Es wird davon ausgegangen, dass Sie bereits mit dem Schreiben von R-Code vertraut sind, die am häufigsten verwendeten Pakete kennen und bereits Shiny-Apps erstellt haben. Mit diesen Beiträgen geben wir einen Rahmen vor, wie Sie den Entwicklungsprozess für Ihre Shiny-Apps organisieren und optimieren können.

In diesem Blog-Post werden wir auf die Bedeutung der Inline-Dokumentation eingehen und ein praktisches Beispiel geben. Natürlich finden Sie alle Informationen auch in unserem kostenlosen Shiny Development Guide!

Shiny-App – Best practice: Inline Documentation

Wenn Sie jetzt denken: „Das weiß ich schon“, dann könnte dieser Beitrag etwas für Sie sein, denn er richtet sich an AnwenderInnen mit Vorkenntnissen in R und Shiny. Es wird jedoch davon ausgegangen, dass Sie bereits mit dem Schreiben von Code in R vertraut sind, die am häufigsten verwendeten Pakete kennen und bereits Shiny-Apps erstellt haben. Mit diesen Beiträgen geben wir einen Rahmen vor, wie Sie den Entwicklungsprozess für Ihre Shiny-Apps organisieren und optimieren können.

In diesem Blog-Post werden wir auf die Bedeutung der Inline-Dokumentation eingehen und ein praktisches Beispiel geben. Natürlich finden Sie alle Informationen auch in unserem kostenlosen Shiny Development Guide!

Warum und wie?

Die Inline-Dokumentation ergänzt, wie der Name schon sagt, ein Projekt bzw. dessen Codem mit Inline-Kommentaren. Wenn der Code nach durchdachten Kodierungsrichtlinien geschrieben wurde, ist es oft nur notwendig, einen kleinen Teil des Codes entsprechend abzudecken. Inline-Dokumentation sollte für komplexe Codeabschnitte oder Code-Teile verwendet werden, die implementiert wurden, um ein bestimmtes Problem zu beheben, das im Nachhinein nicht offensichtlich ist. Diese Art der Dokumentation ermöglicht es den EntwicklerInnen zu verstehen, warum bestimmte Teile des Codes so implementiert wurden, wie sie es sind, und welcher Denkprozess hinter dem spezifischen Code stand. Inline-Dokumentation sollte keine Code-Funktionen duplizieren, die beim Schreiben des Codes klar ersichtlich sind.

Das folgende Beispiel geht davon aus, dass der Datensatz der Pinguine in einer SQL-Datenbank liegt:

# 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-Sprache: 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-Sprache: R (r)