Как мне обращаться с «вспомогательными» функциями в пакете R? - PullRequest
Новая
       15

Как мне обращаться с «вспомогательными» функциями в пакете R?

25 голосов
/ 09 марта 2011

Фон

Я написал пакет R, и теперь соавтор (недавний выпускник CS, новичок в R) редактирует и реорганизует код.В процессе он делит мои функции на более мелкие, более общие функции.

То, что он делает, имеет смысл, но когда я начал с package.skeleton(), у меня был один файл на функцию.Теперь он добавил функции, от которых зависит основная функция, но которые могут иметь ограниченное использование вне самой функции.

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

С тех пор я начал использовать roxygen для документирования каждой функции в тексте.

Вопрос

Какой рекомендуемый способдля обработки функций: очевидно, что вспомогательные функции должны оставаться с основной функцией, но в какой степени мне нужно документировать вспомогательные функции?

Предложение @export в комментариях полезно, но мне интереснознать, как другие организуют свой код.

1 Ответ

28 голосов
/ 31 марта 2011

Я сократил свои функции при двух условиях:

  1. когда это улучшает читаемость кода основной функции и / или
  2. когда он избегает копирования-вставки кода, например, если один и тот же код используется пару раз в одной и той же функции.

Я включаю так называемые вспомогательные функции в файл основной функции, но только до тех пор, пока эти вспомогательные функции не используются ни в одной другой функции. На самом деле, я считаю их вложенными в основную функцию. Я понимаю ваш аргумент в пользу управления версиями, но изменение вспомогательной функции сводится к изменению производительности основной функции, поэтому я не вижу проблем с сохранением их в одном файле.

Некоторые вспомогательные функции могут использоваться в других функциях, и затем я сохраняю их в своем собственном файле. Часто я экспортирую эти функции, поскольку они могут представлять интерес для пользователя. Сравните это, например, с lm и базовым lm.fit, где опытные пользователи могут прилично использовать lm.fit для ускорения кода и т. Д.

Я использую соглашение об именах, используемое во многих пакетах (и производных от linux), предваряя каждую «скрытую» функцию точкой. Так что это 

.helper.function <- function(x, ...){
    ... some code ...
}

main.function <- function(x, ...){
    ...some code, including .helper.function(y, ...)
}

Я явно @export для всех функций, которые нужно экспортировать, но не для вспомогательных функций. Не всегда легко судить, может ли функция представлять интерес для конечного пользователя, но в большинстве случаев это довольно ясно.

В качестве примера: несколько строк кода для обрезки строк NA. Я считаю вспомогательную функцию. Более сложная функция для преобразования набора данных в правильный формат, который я экспортирую и документирую.

YMMV

...