Комментарии в R: как комментировать код (и целые блоки)

Символ

Комментарий в R начинается с #. От этого символа и до конца строки R игнорирует всё:

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

Оба варианта размещения законны: комментарий на отдельной строке или встроенный комментарий после кода. Закрывать нечего — комментарий просто заканчивается там, где заканчивается строка. Одного # достаточно, а # внутри строки в кавычках — это просто символ, а не комментарий:

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

В R нет многострочного комментария

Вот ответ на вопрос, который рано или поздно гуглит каждый новичок в R: в R нет синтаксиса блочных комментариев. Нет ни /* ... */, ни """docstring""", ни =begin/=end. Каждой закомментированной строке нужен свой #. Это осознанная простота языка — и она болезненнее звучит, чем ощущается, потому что пробел закрывает инструментарий.

Решение из реальной жизни: горячая клавиша редактора. В RStudio выделите строки и нажмите Ctrl+Shift+C (Windows/Linux) или Cmd+Shift+C (macOS). Каждая выделенная строка получит префикс #; нажмите ещё раз — и они исчезнут. Именно так и поступают программисты на R, десятки раз в день, и это стоит довести до автоматизма уже на этой неделе. В VS Code, Vim и Emacs есть аналогичные команды переключения комментария для файлов R.

Приём if (FALSE). Поскольку FALSE никогда не истинно, обёртка кода в if (FALSE) { ... } гарантирует, что он никогда не выполнится:

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

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

Знайте о нём, но относитесь как к курьёзу, а не к привычке, потому что у него есть реальные оговорки. Пропускаемый код всё равно должен быть синтаксически корректным R — настоящий блочный комментарий может содержать что угодно, а if (FALSE) вокруг недописанной строки даёт ошибку разбора, которая останавливает весь скрипт. К тому же он молча меняет смысл, если кто-то поправит скобки. Когда нужно отключить строки, безопаснее горячая клавиша редактора; когда нужно их удалить, удаляйте — для этого и существует система контроля версий.

Что говорит хороший комментарий: почему, а не что

Код и так говорит, что он делает. Комментарий, который это повторяет, — шум, который со временем разойдётся с кодом и начнёт врать:

# 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

Второй комментарий несёт информацию, которую код нести не может: почему этот инкремент существует. Это и есть проверка для любого написанного вами комментария — объясняет ли он намерение, контекст или неочевидное решение? Комментарии окупаются на странных строках: обход бага в пакете, намеренная ошибка на единицу, формула из конкретной статьи. И помните правило сопровождения: меняете код — меняйте и комментарий, потому что неверный комментарий хуже, чем никакого.

Если вы ловите себя на том, что пишете комментарий, объясняющий, что хранит переменная, то часто лучшее решение — более понятное имя; этот аргумент разобран в статье про переменные.

Заголовки секций, которые сворачиваются в RStudio

Аналитические скрипты становятся длинными, и комментарии заодно работают как их оглавление. RStudio считает строку комментария, заканчивающуюся четырьмя и более - (или =, или #), заголовком секции:

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

# Clean and reshape ----

# Model ====

Каждая секция становится сворачиваемой и появляется в структуре документа RStudio, так что скрипт на 300 строк превращается в навигируемый список шагов: загрузить, очистить, смоделировать, построить график. Годится любой из завершающих символов, лишь бы их было не меньше четырёх; выберите один стиль и придерживайтесь его. Даже вне RStudio комментарии-заголовки делают структуру скрипта видимой с первого взгляда — это самая дешёвая документация, какая может быть у анализа.

Комментарии roxygen2: #' в дикой природе

Читая чужой код на R — особенно исходники пакетов, — вы встретите комментарии, начинающиеся с #':

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

Это документирующие комментарии roxygen2. Написанные прямо над определением функции, они компилируются инструментарием пакетов в формальные страницы справки, которые вы читаете через ?function_name. Теги (@param, @return) описывают входы и выход функции. Для самого R строка с #' — обычный комментарий; это соглашение имеет силу только внутри инструментария разработки пакетов. Писать их вам не нужно, пока вы не соберёте пакет или не возьмётесь всерьёз документировать свои функции; пока достаточно узнавать их, чтобы исходники пакетов не выглядели загадочно.

Что вы уносите с собой

• # начинает комментарий; он тянется до конца строки — будь то целая строка-комментарий или код, а затем комментарий.
• В R нет многострочного комментария — переключайте блоки через Ctrl/Cmd+Shift+C в RStudio, а if (FALSE) {} берегите для синтаксически корректного кода, который вы пропускаете редко.
• Комментируйте почему, а не что — и обновляйте комментарии при изменении кода.
• Комментарии вида # Section name ---- дают RStudio сворачиваемые секции, а читателям — карту скрипта.
• Строки с #' — это документирующие комментарии roxygen2, которые превращаются в страницы справки пакета.

Дальше: переменные — создание через <-, удачные имена и то, как R обращается с хранящимися в них значениями.