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()
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)AutorIn
Starten Sie jetzt durch:
Wir freuen uns auf den Austausch mit Ihnen.
