R:Оформление кода

Материал Psylab.info - энциклопедии психодиагностики
Версия от 15:19, 9 февраля 2014; Артём Клевцов (обсуждение | вклад) (→‎Названия функций и переменных)

Перейти к: навигация, поиск
Creative Commons
указание авторства 		Материал «R:Оформление кода», созданный автором Артём Клевцов, публикуется на условиях лицензии Creative Commons «Attribution» («Атрибуция») 4.0 Всемирная.
Вы можете свободно:
  • делиться произведением – копировать, распространять и передавать данное произведение.
  • создавать производные – переделывать данное произведение.
При соблюдении следующих условий:
  • указание авторства - Вы должны указывать авторство (источник) данного произведения в виде, установленном автором или лицензиаром (но ни в коем случае не таким образом, который наводит на мысль, что автор поддерживает вас или ваше использование данного произведения).

При совместной работе группы людей над одним проектом часто возникает необходимость в неких общих правилах оформления кода. Целью принятия и использования таких правил является упрощение восприятия программного кода человеком, минимизация нагрузки на память и зрение при чтении его чтении.

К сожалению, для языка R нет чётких правил оформления кода. В качестве источников таких правил обычно используется исходный код ядра R, в котором, правда, наблюдается весьма разнородные варианты оформления. Дополнительными источниками являются стандарты оформления кода, заимствованные из других языков программирования.

Одним из общих правил является необходимость придерживаться одного стиля в рамках одного проекта всего проекта.

Названия файлов

Прежде всего, названия файлов должны быть осмысленными и понятными.

Общим требования к именованию файлов является написания расширений файлов, включающего принадлежность к языку программирования R с большой буквы. Обратим внимание, что все UNIX-like операционные системы чувствительны к регистру в названиях файлов. Например: Шаблон:Inline-code. Бинарный формат хранения данных имеет расширение Шаблон:Inline-code.

Имена файлов содержат символы в нижнем регистре.

Для замены пробелов в названиях файлов обычно используются дефисы или нижние подчёркивания.

Названия функций и переменных

Существуют различные подходы к именованию функций и переменных. Но все они содержат общие рекомендации:

  • Названия должны быть понятны и осмысленны: Шаблон:Inline-code, Шаблон:Inline-code;
  • Названия не должны быть слишком длинными или слишком короткими, что могли бы затруднить их понимание или восприятие;


Можно выделить несколько подходов к именованию функций и переменных:

  • alllowercase (слитное написание, все символы в нижнем регистре, без разделителей). Широко используется в MATLAB. Примеры: Шаблон:Inline-code, Шаблон:Inline-code;
  • period.separated (все символы в нижнем регистре с разделителями в виде точек). Используется только в R. Примеры: Шаблон:Inline-code, Шаблон:Inline-code, Шаблон:Inline-code;
  • underscore_separated (все символы в нижнем регистре с разделителями в виде нижних подчёркиваний). Используется дл именования переменных и функций в C++, Perl, Ruby. Примеры: Шаблон:Inline-code, Шаблон:Inline-code;
  • lowerCamelCase (слитное написание, первый символ в нижнем регистре, начало каждого составного слова в верхнем регистре). Используется во многих языках программирования. Примеры: Шаблон:Inline-code, Шаблон:Inline-code;
  • UpperCamelCase (слитное написание, первый символ в верхнем регистре, начало каждого составного слова в верхнем регистре). Используется во многих языках программирования. Примеры: Шаблон:Inline-code, Шаблон:Inline-code;

В исходном коде R преимущественно используются стили lowerCamelCase, period.separated и underscore_separated. При этом period.separated, как уже отмечалось выше, используется в основном для создания функций для обработки S3 классов.

Название функций

  • Не использовать имена уже используются в R или популярных пакетах. Для проверки уже используемых имён можно использовать функции Шаблон:Inline-code и Шаблон:Inline-code;
  • Избегать использование точек в названиях переменных, если только данные функции не предназначены для работы с S3 классами;

Название переменных

Присвоение

Для присвоения используется «<-» или «->», но не «=», который используется только для указания значения аргументов функций.

Отступы

Для отступов могут использоваться как пробелы, так и табуляция. В R coding standards рекомендуется использовать 4 пробела для кода и 2 пробела для документации. В Google's R Style Guide рекомендуется использоваться 2 пробела. Важно, чтобы отступы были везде одинаковыми, т.е. только пробелы или только табуляция.

Расстановка пробелов

Пробелы ставятся до и после математических символов и бинарных или логических операторов:

  • математические символы: «=», «+», «-», «*», «/»;
  • операторы присвоения: «<-», «->»
  • бинарные операторы: «%in%», «%%», «%/%»;
  • логические операторы: «==», «!=», «&», «|», «<», «>», «<=», «>=».

Пробелы также ставятся после запятых.

Пробелы ставятся перед открывающейся фигурной скобкой - «{».

Пробелы ставятся перед открывающейся круглой скобкой - «(», за исключением объявления или вызова функции.

Пробелы также не ставятся между круглыми скобками:

<syntaxhighlight lang="rsplus"> if ( (x == 1) & (y == 2) ) </syntaxhighlight>

Более корректно:

<syntaxhighlight lang="rsplus"> if ((x == 1) & (y == 2)) </syntaxhighlight>

Рекомендуется отделять пробелами оператор присвоения значений аргументов:

<syntaxhighlight lang="rsplus"> plot(x,y, lwd=4, col=green, main="My Title") </syntaxhighlight>

Более корректно:

<syntaxhighlight lang="rsplus"> plot(x,y, lwd = 4, col = green, main = "My Title") </syntaxhighlight>

Общая логика и порядок написания скриптов

  1. Комментарий, содержащий информацию о лицензии, под которой распространяется код;
  2. Комментарий, содержащий информацию об авторе;
  3. Комментарий, содержащий информацию о содержании и назначении скрипта;
  4. Импорт пакетов и скриптов - вызов Шаблон:Inline-code и Шаблон:Inline-code;
  5. Объявления функций:
  6. Выполнение основный выражений.

Ссылки

Источник — «https://psylab.info/index.php?title=R:Оформление_кода&oldid=7483»