tablas - ¿Cómo debo manejar las funciones de ''ayuda'' en un paquete R?

tablas en r

Question

Fondo

Escribí un paquete de R, y ahora un colaborador (reciente graduado de CS que es nuevo en R) está editando y refactorizando el código. En el proceso, él está dividiendo mis funciones en funciones más pequeñas y genéricas.

Lo que está haciendo tiene sentido, pero cuando empecé con package.skeleton() , tenía un archivo por función. Ahora, él ha agregado funciones de las que depende la función principal, pero que puede tener un uso limitado fuera de la función en sí.

Él sugiere que todas las funciones van en un solo archivo, pero estoy en contra porque es más fácil hacer el control de versiones cuando trabajamos en diferentes archivos.

Desde entonces, he empezado a usar roxygen para documentar cada función dentro del texto.

Pregunta

¿Cuál es la forma recomendada de manejar las funciones: claramente las funciones de ayuda deben permanecer con la función principal, pero hasta qué punto necesito documentar las funciones de ayuda?

La sugerencia de @export en los comentarios es útil, pero tengo curiosidad por saber cómo otros organizan su código.

Answer 1

Corté mis funciones bajo dos condiciones:

1. cuando mejora la legibilidad del código de la función principal, y / o
2. cuando evita copiar y pegar código, por ejemplo, si el mismo código se usa un par de veces dentro de la misma función.

Incluyo las llamadas funciones de ayuda en el archivo de la función principal, pero solo mientras esas funciones de ayuda no se usen en ninguna otra función. En realidad, los considero anidados dentro de la función principal. Entiendo su argumento para el control de versiones, pero cambiar la función auxiliar se reduce a cambiar el rendimiento de la función principal, por lo que no veo ningún problema en mantenerlos en el mismo archivo.

Algunas funciones de ayuda podrían usarse en otras funciones diferentes, y luego las guardo en su propio archivo. A menudo exporto esas funciones, ya que pueden ser de interés para el usuario. Compare esto con, por ejemplo, lm y el lm.fit subyacente, donde los usuarios avanzados podrían hacer un uso decente de lm.fit para acelerar el código, etc.

Utilizo la convención de nomenclatura utilizada en algunos paquetes (y derivados de Linux), precediendo cada función "oculta" por un punto. Así que eso hace

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

Explico explícitamente todas las funciones que necesitan exportar, nunca las funciones auxiliares. No siempre es fácil juzgar si una función puede ser de interés para un usuario final, pero en la mayoría de los casos es bastante claro.

Para dar un ejemplo: algunas líneas de código para cortar las líneas de NA considero una función auxiliar. Una función más compleja para convertir el conjunto de datos al formato correcto que exporto y documento.

YMMV