Как я должен обрабатывать функции "помощника" в R-пакете?

Фон

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

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

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

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

Вопрос

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

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

Ответ 1

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

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

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

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

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

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

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

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

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

YMMV