0Pricing
R Academy · Урок

Комментарии, стиль и читаемость

Пишите чистый документированный код R, следуя руководству по стилю tidyverse.

«Комментарии, стиль и читаемость» — бесплатный урок R Academy на CoddyKit. Это урок 2 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения R Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс R Academy содержит 4 уроков всего.

Однострочные комментарии с помощью #

В R символ # начинает комментарий. Всё от # до конца строки игнорируется интерпретатором. Комментарии предназначены для людей — объясняйте почему, а не только что.

# This is a comment — R ignores it completely
x <- 42   # inline comment after code

# Bad comment (states the obvious):
y <- y + 1   # add 1 to y

# Good comment (explains intent):
y <- y + 1   # shift index to 1-based for output display

cat('x =', x)

Заголовки разделов с помощью ------

Широко распространённое соглашение в R — создавать заголовки разделов, добавляя после текста комментария как минимум четыре тире, знака равенства или решётки. RStudio распознаёт их и добавляет в структуру документа для удобной навигации.

# Data Loading -------------------------------------------------------

# This section loads raw CSV files from the data/ folder

# Data Cleaning =======================================================

# Remove duplicates and fix missing values

# Modeling ############################################################

# Fit linear model and evaluate

cat('Section headers improve navigation')

Соглашение об именовании snake_case

Руководство по стилю tidyverse рекомендует использовать snake_case для всех имён объектов: слова в нижнем регистре разделяются символами подчёркивания. Для единообразия избегайте точек (в других языках они выглядят как вызовы методов) и camelCase.

# Good: snake_case
user_age <- 25
monthly_revenue <- 15000
calculate_mean <- function(x) mean(x)

# Avoid: dots in names (looks like OOP method calls)
user.age <- 25       # confusing

# Avoid: camelCase (inconsistent with tidyverse)
userAge <- 25

# Avoid: ALL_CAPS (reserved for true constants by convention)
MAX_RETRIES <- 3     # acceptable for config constants only

cat('snake_case wins')

Пробелы вокруг операторов

Всегда ставьте пробелы вокруг операторов присваивания и сравнения. Это значительно улучшает читаемость. Единственное исключение — списки аргументов функций, где = связывает имена аргументов со значениями.

# Good: spaces around <- and operators
x <- 10
y <- x + 5
result <- x * y - 2
is_valid <- x > 0 & y < 100

# Bad: cramped
x<-10
y<-x+5

# Function arguments: = without extra spaces is fine
mean(x = c(1, 2, 3), na.rm = TRUE)

# Comparison operators also need spaces
if (x > 0) cat('positive')
if (x >= 0 & y <= 100) cat('in range')

Используйте <-, а не =, для присваивания

Хотя R допускает = для присваивания на верхнем уровне, общепринято использовать <- для присваивания объектам, оставляя = исключительно для значений аргументов функций. Благодаря этому различию код гораздо легче читать с первого взгляда.

# Correct: <- for assignment
name <- 'Alice'
score <- 95.5
results <- c(1, 2, 3)

# Correct: = inside function calls
round(3.14159, digits = 2)
read.csv('data.csv', header = TRUE, sep = ',')

# Avoid: = for top-level assignment
# name = 'Alice'   <- works but not idiomatic

cat('Assignment convention:', name, score)

Ограничение в 80 символов на строку

Строки длиной менее 80 символов удобно читать в редакторах с разделёнными панелями, на распечатанных страницах и в инструментах проверки кода. В RStudio можно включить направляющую поля на 80-м столбце через Сервис → Глобальные параметры → Код → Отображение.

# Bad: one very long line (hard to read)
result <- some_function(argument_one = 'value', argument_two = 100, argument_three = TRUE, argument_four = 'long_string')

# Good: break at commas, indent continuation
result <- some_function(
  argument_one   = 'value',
  argument_two   = 100,
  argument_three = TRUE,
  argument_four  = 'long_string'
)

cat('Readable at 80 chars')

Без точек с запятой

В отличие от JavaScript и C, R не требует ставить точки с запятой в конце операторов. Точки с запятой можно использовать, чтобы разместить несколько операторов в одной строке, но руководство по стилю рекомендует: один оператор в строке, без точек с запятой.

# Bad: semicolons and multiple statements per line
x <- 1; y <- 2; z <- x + y

# Good: one statement per line
x <- 1
y <- 2
z <- x + y

# The semicolon form is only acceptable in very short
# interactive throwaway code, never in scripts
cat('z =', z)

Понятные имена переменных

Выбирайте имена, которые описательны, но не чрезмерно длинны. Хорошее правило: если через полгода Вам приходится больше секунды думать, чтобы понять имя переменной, оно слишком короткое или слишком загадочное.

# Too cryptic:
d <- read.csv('data.csv')
tmp <- d[d$v1 > 0, ]
r <- lm(v2 ~ v1, data = tmp)

# Good names:
sales_data    <- read.csv('data.csv')
positive_rows <- sales_data[sales_data$revenue > 0, ]
revenue_model <- lm(profit ~ revenue, data = positive_rows)

# Avoid abbreviations that are not universally understood:
# n_obs is fine (number of observations)
# nrv is not (nobody knows what this is)

cat('Names tell the story')

Фигурные скобки и отступы

Руководство по стилю tidyverse устанавливает следующие правила: открывающая скобка { находится в той же строке, а закрывающая } — в отдельной строке. Используйте для отступов 2 пробела, а не табуляцию. Единообразные отступы важны для чтения вложенной логики.

# Good style: brace on same line, 2-space indent
if (x > 0) {
  cat('positive\n')
} else {
  cat('non-positive\n')
}

# Good function definition:
calculate_bmi <- function(weight_kg, height_m) {
  bmi <- weight_kg / height_m^2
  round(bmi, 1)
}

cat('BMI:', calculate_bmi(70, 1.75))

Пробелы внутри скобок и после запятых

Ставьте пробел после каждой запятой (как в письменном английском), но не ставьте пробел перед запятой или непосредственно внутри скобок. Это соответствует математической записи и упрощает чтение индексации.

# Good: space after comma, not before
x <- c(1, 2, 3, 4, 5)
m <- matrix(1:9, nrow = 3, ncol = 3)

# Subsetting: no space before [ or inside []
first_row <- m[1, ]      # good
value     <- m[2, 3]    # good

# Bad:
# c(1,2,3)     <- no space after comma
# m[ 1, ]      <- space after [
# m[1 , ]      <- space before comma

cat('Spacing is consistent')

Использование styler и lintr

Два инструмента автоматизируют соблюдение стиля в R. styler переформатирует код в соответствии с руководством по стилю tidyverse. lintr статически проверяет стиль кода и возможные ошибки, не выполняя его. Оба инструмента интегрируются с RStudio.

# styler: reformat a file automatically
# install.packages('styler')
# styler::style_file('my_script.R')

# styler: reformat the whole project
# styler::style_dir('R/')

# lintr: check for style and potential bugs
# install.packages('lintr')
# lintr::lint('my_script.R')

# lintr reports issues like:
#   line 10: [object_name_linter] Variable 'myVar' should use snake_case
#   line 15: [spaces_around_ops_linter] No space before '<-'

cat('Style tools: styler + lintr')

Быстрая проверка

Согласно руководству по стилю tidyverse, какой из вариантов правильно записывает оператор присваивания в R?

Стиль и читаемость — главное

Хорошо оформленный код на R профессионален, удобен в сопровождении и подходит для совместной работы:

  • # для комментариев — объясняйте почему, а не только что
  • Заголовки разделов с ------ или ====== для навигации
  • snake_case для всех имён объектов и функций
  • Пробелы вокруг <-, +, == и других операторов
  • Используйте <- для присваивания, а = — только в аргументах функций
  • Не более 80 символов в строке — переносите длинные вызовы на несколько строк
  • Без точек с запятой — один оператор в строке
  • Отступ в 2 пробела, открывающая { в той же строке
  • Используйте styler для автоматического форматирования, а lintr — для обнаружения проблем
# Putting it all together:

# Calculate summary statistics ----------------------------------------
calculate_summary <- function(values, remove_na = TRUE) {
  cleaned <- values[!is.na(values)]
  list(
    mean   = mean(cleaned),
    median = median(cleaned),
    sd     = sd(cleaned)
  )
}

test_scores <- c(85, 90, NA, 78, 92, 88)
stats <- calculate_summary(test_scores)
cat('Mean:', stats$mean, '\n')
cat('SD:  ', stats$sd)

Часто задаваемые вопросы

Урок «Комментарии, стиль и читаемость» бесплатный?

Да — полный текст урока «Комментарии, стиль и читаемость» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс R Academy, подпишись на CoddyKit PRO. Курс R Academy содержит 4 уроков всего.

Чему я научусь в уроке «Комментарии, стиль и читаемость»?

Пишите чистый документированный код R, следуя руководству по стилю tidyverse. Ты практикуешь R Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать R Academy?

Предыдущий опыт не требуется. R Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 2 из 4.

Сколько времени занимает урок «Комментарии, стиль и читаемость»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке R Academy?

Да. Каждый урок R Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

  1. Загрузка скриптов с помощью source()
  2. Комментарии, стиль и читаемость
  3. Рабочие каталоги и пути к файлам
  4. Проекты R и управление рабочей областью
← Назад к R Academy