R:Оформление кода — различия между версиями
м (→Присвоение) |
м |
||
Строка 21: | Строка 21: | ||
Существуют различные подходы к именованию функций и переменных. Но все они содержат общие рекомендации: | Существуют различные подходы к именованию функций и переменных. Но все они содержат общие рекомендации: | ||
− | * Названия должны быть понятны и осмысленны: | + | * Названия должны быть понятны и осмысленны: <code>colMeans</code>, <code>read.table</code>; |
* Названия не должны быть слишком длинными или слишком короткими, что могли бы затруднить их понимание или восприятие; | * Названия не должны быть слишком длинными или слишком короткими, что могли бы затруднить их понимание или восприятие; | ||
− | * Не использовать имена уже используются в R или популярных пакетах. Для проверки уже используемых имён можно использовать функции | + | * Не использовать имена уже используются в R или популярных пакетах. Для проверки уже используемых имён можно использовать функции <code>find()</code> и <code>apropos()</code>; |
Можно выделить несколько подходов к именованию функций и переменных: | Можно выделить несколько подходов к именованию функций и переменных: | ||
− | * alllowercase (слитное написание, все символы в нижнем регистре, без разделителей). Широко используется в MATLAB. Примеры: | + | * alllowercase (слитное написание, все символы в нижнем регистре, без разделителей). Широко используется в MATLAB. Примеры: <code>searchpaths</code>, <code>searchpaths</code>; |
− | * period.separated (все символы в нижнем регистре с разделителями в виде точек). Используется только в R. Примеры: | + | * period.separated (все символы в нижнем регистре с разделителями в виде точек). Используется только в R. Примеры: <code>as.numeric</code>, <code>read.table</code>, <code>data.frame</code>; |
− | * underscore_separated (все символы в нижнем регистре с разделителями в виде нижних подчёркиваний). Используется дл именования переменных и функций в C++, Perl, Ruby. Примеры: | + | * underscore_separated (все символы в нижнем регистре с разделителями в виде нижних подчёркиваний). Используется дл именования переменных и функций в C++, Perl, Ruby. Примеры: <code>package_version</code>, <code>seq_along</code>; |
− | * lowerCamelCase (слитное написание, первый символ в нижнем регистре, начало каждого составного слова в верхнем регистре). Используется во многих языках программирования. Примеры: | + | * lowerCamelCase (слитное написание, первый символ в нижнем регистре, начало каждого составного слова в верхнем регистре). Используется во многих языках программирования. Примеры: <code>colMeans</code>, <code>suppressPackageStartupMessage.</code>; |
− | * UpperCamelCase (слитное написание, первый символ в верхнем регистре, начало каждого составного слова в верхнем регистре). Используется во многих языках программирования. Примеры: | + | * UpperCamelCase (слитное написание, первый символ в верхнем регистре, начало каждого составного слова в верхнем регистре). Используется во многих языках программирования. Примеры: <code>Vectorize</code>, <code>NextMethod</code>; |
В различных руководствах приводятся разные рекомендации. Как мы уже отмечали, гораздо более важно придерживаться единого стиля при написании кода. В исходном коде R преимущественно используются стили lowerCamelCase, period.separated и underscore_separated. При этом period.separated, как уже отмечалось выше, используется в основном для создания функций для обработки S3 классов. | В различных руководствах приводятся разные рекомендации. Как мы уже отмечали, гораздо более важно придерживаться единого стиля при написании кода. В исходном коде R преимущественно используются стили lowerCamelCase, period.separated и underscore_separated. При этом period.separated, как уже отмечалось выше, используется в основном для создания функций для обработки S3 классов. | ||
Строка 86: | Строка 86: | ||
# Комментарий, содержащий информацию об авторе; | # Комментарий, содержащий информацию об авторе; | ||
# Комментарий, содержащий информацию о содержании и назначении скрипта; | # Комментарий, содержащий информацию о содержании и назначении скрипта; | ||
− | # Импорт пакетов и скриптов - вызов | + | # Импорт пакетов и скриптов - вызов <code>library()</code> и <code>source()</code>; |
# Объявления функций: | # Объявления функций: | ||
# Выполнение основный выражений. | # Выполнение основный выражений. |
Версия 15:59, 13 февраля 2014
|
Материал «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="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>
Общая логика и порядок написания скриптов
- Комментарий, содержащий информацию о лицензии, под которой распространяется код;
- Комментарий, содержащий информацию об авторе;
- Комментарий, содержащий информацию о содержании и назначении скрипта;
- Импорт пакетов и скриптов - вызов
library()
иsource()
; - Объявления функций:
- Выполнение основный выражений.
Ссылки
- 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