Komentarze w R: jak komentować kod (i zakomentować bloki)

Symbol

Komentarz w R zaczyna się od #. Od tego znaku do końca linii R wszystko ignoruje:

# 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)

Oba miejsca są poprawne: komentarz w osobnej linii albo komentarz w linii po kodzie. Nie trzeba niczego zamykać, bo komentarz po prostu kończy się razem z linią. Wystarczy jeden #, a # wewnątrz napisu w cudzysłowie to zwykły znak, nie komentarz:

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

R nie ma komentarza wielolinijkowego

Oto odpowiedź na pytanie, które każdy początkujący w R prędzej czy później wpisuje w Google: R nie ma składni komentarza blokowego. Nie ma /* ... */, nie ma """docstring""", nie ma =begin/=end. Każda zakomentowana linia potrzebuje własnego #. To celowa prostota języka i w praktyce jest mniej uciążliwa, niż się wydaje, bo lukę wypełniają narzędzia.

Rozwiązanie z prawdziwego życia: skrót przełączania komentarza w edytorze. W RStudio zaznacz linie i naciśnij Ctrl+Shift+C (Windows/Linux) lub Cmd+Shift+C (macOS). Każda zaznaczona linia dostaje na początku #; naciśnij skrót jeszcze raz, a znaki znikną. Tak właśnie robią programiści R, dziesiątki razy dziennie, więc warto jeszcze w tym tygodniu wyćwiczyć ten ruch. VS Code, Vim i Emacs mają podobne polecenia przełączania komentarza dla plików R.

Sztuczka z if (FALSE). Ponieważ FALSE nigdy nie jest prawdą, kod owinięty w if (FALSE) { ... } na pewno się nie wykona:

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

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

Warto ją znać, ale traktuj ją raczej jako ciekawostkę niż nawyk, bo ma realne wady. Pomijany kod nadal musi być składniowo poprawnym kodem R. Prawdziwy komentarz blokowy może zawierać cokolwiek, a if (FALSE) wokół niedokończonej linii to błąd parsowania, który zatrzymuje cały skrypt. Znaczenie kodu zmienia się też po cichu, jeśli ktoś przerobi nawiasy klamrowe. Gdy chcesz wyłączyć linie, bezpieczniejszy jest skrót w edytorze; gdy chcesz się ich pozbyć, usuń je. Od tego jest system kontroli wersji.

Co mówi dobry komentarz: dlaczego, a nie co

Kod już mówi, co robi. Komentarz, który to powtarza, jest szumem, który z czasem się zdezaktualizuje i zacznie kłamać:

# 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

Drugi komentarz niesie informację, której kod nie przekaże: dlaczego istnieje to zwiększenie. To test dla każdego komentarza, który piszesz: czy wyjaśnia intencję, kontekst albo nieoczywistą decyzję? Komentarze są najcenniejsze przy dziwnych liniach: obejściu błędu w pakiecie, celowym przesunięciu o jeden, wzorze wziętym z konkretnego artykułu. I pamiętaj o zasadzie utrzymania: kiedy zmieniasz kod, zmień też jego komentarz, bo błędny komentarz jest gorszy niż żaden.

Jeśli piszesz komentarz, żeby wyjaśnić, co przechowuje zmienna, często lepszym rozwiązaniem jest czytelniejsza nazwa. Więcej o tym w artykule o zmiennych.

Nagłówki sekcji zwijane w RStudio

Skrypty analityczne szybko się wydłużają, a komentarze służą przy okazji za spis treści. RStudio traktuje linię komentarza zakończoną czterema lub więcej znakami - (albo = lub #) jako nagłówek sekcji:

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

# Clean and reshape ----

# Model ====

Każdą sekcję da się zwinąć i pojawia się ona w konspekcie dokumentu w RStudio, więc skrypt na 300 linii zamienia się w listę kroków, po której łatwo się poruszać: wczytanie, czyszczenie, model, wykres. Działa każdy z tych znaków, o ile są co najmniej cztery; wybierz jeden styl i trzymaj się go. Nawet poza RStudio komentarze z nagłówkami sekcji pokazują strukturę skryptu na pierwszy rzut oka. To najtańsza dokumentacja, jaką może mieć analiza.

Komentarze roxygen2: #' w praktyce

Czytając cudzy kod R, zwłaszcza kod źródłowy pakietów, trafisz na komentarze zaczynające się od #':

#' 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
}

To komentarze dokumentacji roxygen2. Pisane bezpośrednio nad definicją funkcji, są kompilowane przez narzędzia pakietowe do formalnych stron pomocy, które czytasz przez ?function_name. Znaczniki (@param, @return) opisują dane wejściowe i wynik funkcji. Dla samego R linia #' to zwykły komentarz: ta konwencja działa tylko w narzędziach do tworzenia pakietów. Nie musisz ich pisać, dopóki nie zbudujesz pakietu albo nie zaczniesz na poważnie dokumentować własnych funkcji. Na razie wystarczy, że je rozpoznasz, żeby kod źródłowy pakietów nie wyglądał tajemniczo.

Najważniejsze informacje

• # rozpoczyna komentarz, który trwa do końca linii, niezależnie od tego, czy cała linia jest komentarzem, czy komentarz stoi po kodzie.
• R nie ma komentarza wielolinijkowego: przełączaj bloki skrótem Ctrl/Cmd+Shift+C w RStudio, a if (FALSE) {} zostaw dla składniowo poprawnego kodu, który rzadko pomijasz.
• Komentuj dlaczego, a nie co, i aktualizuj komentarze, gdy zmienia się kod.
• Komentarze # Section name ---- dają w RStudio zwijane sekcje, a czytelnikom mapę skryptu.
• Linie #' to komentarze dokumentacji roxygen2, z których powstają strony pomocy pakietów.

Dalej: zmienne, czyli jak tworzyć je przez <-, dobrze je nazywać i jak R traktuje przechowywane w nich wartości.