R:Оформление кода
 
|
Материал «R:Оформление кода», созданный автором Артём Клевцов, публикуется на условиях лицензии Creative Commons «Attribution» («Атрибуция») 4.0 Всемирная. | |
|
При совместной работе группы людей над одним проектом часто возникает необходимость в неких общих правилах оформления кода. Целью принятия и использования таких правил является упрощение восприятия программного кода человеком, минимизация нагрузки на память и зрение при чтении его чтении.
К сожалению, для языка R нет чётких правил оформления кода. В качестве источников таких правил обычно используется исходный код ядра R, в котором, правда, наблюдается весьма разнородные варианты оформления. Дополнительными источниками являются стандарты оформления кода, заимствованные из других языков программирования.
Одним из общих правил является необходимость придерживаться одного стиля в рамках одного проекта всего проекта.
Содержание
Названия файлов
Прежде всего, названия файлов должны быть осмысленными и понятными.
Общим требования к именованию файлов является написания расширений файлов, включающего принадлежность к языку программирования R с большой буквы. Обратим внимание, что все UNIX-like операционные системы чувствительны к регистру в названиях файлов. Например: Шаблон:Inline-code. Бинарный формат хранения данных имеет расширение Шаблон:Inline-code.
Имена файлов содержат символы в нижнем регистре.
Для замены пробелов в названиях файлов обычно используются дефисы или нижние подчёркивания.
Названия функций и переменных
Существуют различные подходы к именованию функций и переменных. Но все они содержат общие рекомендации:
- Названия должны быть понятны и осмысленны:
colMeans,read.table; - Названия не должны быть слишком длинными или слишком короткими, что могли бы затруднить их понимание или восприятие;
- Не использовать имена уже используются в R или популярных пакетах. Для проверки уже используемых имён можно использовать функции
find()иapropos();
Можно выделить несколько подходов к именованию функций и переменных:
- alllowercase (слитное написание, все символы в нижнем регистре, без разделителей). Широко используется в MATLAB. Примеры:
searchpaths,searchpaths; - period.separated (все символы в нижнем регистре с разделителями в виде точек). Используется только в R. Примеры:
as.numeric,read.table,data.frame; - underscore_separated (все символы в нижнем регистре с разделителями в виде нижних подчёркиваний). Используется дл именования переменных и функций в C++, Perl, Ruby. Примеры:
package_version,seq_along; - lowerCamelCase (слитное написание, первый символ в нижнем регистре, начало каждого составного слова в верхнем регистре). Используется во многих языках программирования. Примеры:
colMeans,suppressPackageStartupMessage.; - UpperCamelCase (слитное написание, первый символ в верхнем регистре, начало каждого составного слова в верхнем регистре). Используется во многих языках программирования. Примеры:
Vectorize,NextMethod;
В различных руководствах приводятся разные рекомендации. Как мы уже отмечали, гораздо более важно придерживаться единого стиля при написании кода. В исходном коде R преимущественно используются стили lowerCamelCase, period.separated и underscore_separated. При этом period.separated, как уже отмечалось выше, используется в основном для создания функций для обработки S3 классов.
Присвоение
Для присвоения используется «<-» или «->», но не «=», который используется только для указания значений аргументов функций.
Отступы
Для отступов могут использоваться как пробелы, так и табуляция. В R coding standards рекомендуется использовать 4 пробела для кода и 2 пробела для документации. В Google's R Style Guide рекомендуется использоваться 2 пробела. Важно, чтобы отступы были везде одинаковыми, т.е. только пробелы или только табуляция.
Расстановка пробелов
Пробелы ставятся до и после математических символов и бинарных или логических операторов:
- математические символы: «=», «+», «-», «*», «/»;
- операторы присвоения: «<-», «->»;
- бинарные операторы: «%in%», «%%», «%/%»;
- логические операторы: «==», «!=», «&», «|», «<», «>», «<=», «>=».
Пробелы также ставятся после запятых.
Пробелы ставятся перед открывающейся фигурной скобкой - «{».
Пробелы ставятся перед открывающейся круглой скобкой - «(», за исключением объявления или вызова функции.
Пробелы также не ставятся между круглыми скобками:
<syntaxhighlight lang="r">if ( (x == 1) & (y == 2) )</syntaxhighlight>
Более корректно:
<syntaxhighlight lang="r">if ((x == 1) & (y == 2))</syntaxhighlight>
Рекомендуется отделять пробелами оператор присвоения значений аргументов:
{{r-code|code=plot(x,y, lwd=4, col=green, main="My Title")}} Более корректно: {{r-code|code=<nowiki>plot(x,y, lwd = 4, col = green, main = "My Title")}} == Общая логика и порядок написания скриптов == # Комментарий, содержащий информацию о лицензии, под которой распространяется код; # Комментарий, содержащий информацию об авторе; # Комментарий, содержащий информацию о содержании и назначении скрипта; # Импорт пакетов и скриптов - вызов <code>library()</code> и <code>source()</code>; # Объявления функций: # Выполнение основный выражений. === Ссылки === * R Style. An Rchaeological Commentary - http://cran.r-project.org/web/packages/rockchalk/vignettes/Rstyle.pdf * Google's R Style Guide - http://google-styleguide.googlecode.com/svn/trunk/Rguide.xml * Style guide - http://adv-r.had.co.nz/Style.html * The State of Naming Conventions in R - http://journal.r-project.org/archive/2012-2/RJournal_2012-2_Baaaath.pdf * R Coding Conventions (RCC) - http://www.aroma-project.org/developers/RCC [[Категория:R]] [[Категория:Оптимизация кода]]
