Kommentare in R: Code kommentieren (und Blöcke auskommentieren)

Das #-Zeichen

Ein Kommentar in R beginnt mit #. Von diesem Zeichen bis zum Zeilenende ignoriert R alles:

# This whole line is a comment. R skips it.
speed_kmh <- 90

speed_ms <- speed_kmh / 3.6  # convert to meters per second

print(speed_ms)

Beide Platzierungen sind legal: ein Kommentar auf eigener Zeile oder ein Inline-Kommentar hinter Code. Es gibt nichts zu schließen - der Kommentar endet einfach dort, wo die Zeile endet. Ein # genügt, und ein # innerhalb eines Strings in Anführungszeichen ist nur ein Zeichen, kein Kommentar:

tag <- "#1 fan"  # the first # is data, this one is a comment
print(tag)

R hat keinen mehrzeiligen Kommentar

Hier die Antwort auf die Frage, die jeder R-Anfänger irgendwann googelt: R hat keine Blockkommentar-Syntax. Es gibt kein /* ... */, keinen """docstring""", kein =begin/=end. Jede kommentierte Zeile braucht ihr eigenes #. Das ist eine bewusste Einfachheit der Sprache - und weniger schmerzhaft, als es klingt, weil das Tooling die Lücke füllt.

Die Praxislösung: der Umschalt-Shortcut des Editors. In RStudio die Zeilen markieren und Strg+Shift+C (Windows/Linux) bzw. Cmd+Shift+C (macOS) drücken. Jede markierte Zeile erhält ein #-Präfix; erneut drücken, und sie sind weg. Genau das tun R-Programmierer tatsächlich, dutzende Male am Tag, und es lohnt sich, das noch diese Woche ins Muskelgedächtnis zu bringen. VS Code, Vim und Emacs haben alle entsprechende Toggle-Comment-Befehle für R-Dateien.

Der if (FALSE)-Trick. Weil FALSE nie wahr ist, garantiert das Einwickeln von Code in if (FALSE) { ... }, dass er nie läuft:

if (FALSE) {
    expensive_call <- 1 / 0
    cat("you will never see this\n")
}

cat("but you will see this\n")

Man sollte ihn kennen, aber als Kuriosität behandeln statt als Gewohnheit, denn er hat echte Vorbehalte. Der übersprungene Code muss weiterhin syntaktisch gültiges R sein - ein echter Blockkommentar kann alles enthalten, aber if (FALSE) um eine halb geschriebene Zeile ist ein Parse-Fehler, der das ganze Skript stoppt. Außerdem ändert er still die Bedeutung, wenn die geschweiften Klammern editiert werden. Wer Zeilen deaktivieren will, fährt mit dem Editor-Shortcut sicherer; wer sie loswerden will, löscht sie - dafür gibt es Versionskontrolle.

Was gute Kommentare aussagen: Warum, nicht Was

Der Code sagt bereits, was er tut. Ein Kommentar, der das wiederholt, ist Rauschen, das irgendwann veraltet und zu lügen beginnt:

# Bad: narrates the obvious
x <- x + 1  # add 1 to x

# Good: explains the reason
x <- x + 1  # customer-facing IDs are 1-based, data is 0-based

Der zweite Kommentar trägt Information, die der Code nicht liefern kann: warum es das Inkrement gibt. Das ist der Test für jeden Kommentar - erklärt er Absicht, Kontext oder eine nicht offensichtliche Entscheidung? Kommentare verdienen ihren Platz an den seltsamen Zeilen: der Workaround für einen Paket-Bug, das absichtliche Off-by-One, die Formel aus einem bestimmten Paper. Und die Wartungsregel nicht vergessen: Wer den Code ändert, ändert auch dessen Kommentar, denn ein falscher Kommentar ist schlimmer als keiner.

Wer sich dabei ertappt, einen Kommentar zu schreiben, der erklärt, was eine Variable enthält, ist mit einem klareren Namen oft besser bedient - das Argument dazu steht bei den Variablen.

Abschnittsüberschriften, die sich in RStudio falten lassen

Analyseskripte werden lang, und Kommentare dienen zugleich als ihr Inhaltsverzeichnis. RStudio behandelt eine Kommentarzeile, die mit vier oder mehr - (oder = oder #) endet, als Abschnittsüberschrift:

# Load data ----------------------------------------------------------

# Clean and reshape ----

# Model ====

Jeder Abschnitt wird faltbar und erscheint in RStudios Dokument-Gliederung, sodass ein 300-Zeilen-Skript zu einer navigierbaren Schrittliste wird: laden, bereinigen, modellieren, plotten. Jedes der Endzeichen funktioniert, solange es mindestens vier sind; einen Stil wählen und konsequent bleiben. Auch außerhalb von RStudio machen Abschnittskommentare die Struktur eines Skripts auf einen Blick sichtbar - die günstigste Dokumentation, die eine Analyse haben kann.

roxygen2-Kommentare: #' in freier Wildbahn

Wer fremden R-Code liest - vor allem Paket-Quellcode -, trifft auf Kommentare, die mit #' beginnen:

#' Convert a speed from km/h to m/s
#'
#' @param kmh Speed in kilometers per hour.
#' @return Speed in meters per second.
kmh_to_ms <- function(kmh) {
    kmh / 3.6
}

Das sind roxygen2-Dokumentationskommentare. Direkt über einer Funktionsdefinition geschrieben, werden sie vom Paket-Tooling zu den formalen Hilfeseiten kompiliert, die man mit ?function_name liest. Die Tags (@param, @return) beschreiben Ein- und Ausgabe der Funktion. Für R selbst ist eine #'-Zeile ein gewöhnlicher Kommentar - die Konvention hat nur innerhalb der Paketentwicklungs-Werkzeugkette Kraft. Man muss sie erst schreiben, wenn man ein Paket baut oder eigene Funktionen ernsthaft dokumentiert; fürs Erste reicht es, sie zu erkennen, damit Paket-Quellcode nicht rätselhaft wirkt.

Was bleibt hängen

• # startet einen Kommentar; er reicht bis zum Zeilenende, egal ob die Zeile nur Kommentar ist oder Code-dann-Kommentar.
• R hat keinen mehrzeiligen Kommentar - Blöcke mit Strg/Cmd+Shift+C in RStudio umschalten und if (FALSE) {} für syntaktisch gültigen, selten übersprungenen Code reservieren.
• Das Warum kommentieren, nicht das Was - und Kommentare aktualisieren, wenn sich der Code ändert.
• # Abschnittsname -----Kommentare geben RStudio faltbare Abschnitte und Lesern eine Landkarte des Skripts.
• #'-Zeilen sind roxygen2-Doku-Kommentare, die zu Paket-Hilfeseiten werden.

Als Nächstes: Variablen - sie mit <- anlegen, gut benennen, und wie R die Werte behandelt, die sie enthalten.