Guía de estilo de R (de Google)

R es un lenguaje de programación de alto nivel que se usa principalmente en aplicaciones estadísticas y para la generación de gráficos. El objetivo de esta guía de estilo es que nuestro código sea más fácil de leer, compartir y analizar. Las reglas de esta guía fueron consensuadas con la comunidad de usuarios de R en Google.

Resumen de las reglas de estilo
1. Nombres de ficheros: tienen la extensión .R
2. Identificacores: variable.name, FunctionName, kConstantName
3. Longitud de línea: no más de 80 caracteres
4. Indentación: dos espacios, no tabuladores
5. Espacios
6. Llaves: el primero en la misma línea; el último, solo
7. Asignaciones: usar <-, no =
8. Puntos y comas: no usarlos
9. Distribución general y ordenación
10. Comentarios: todos los comentarios comienzan con # seguido de un espacio; los comentarios dentro del código necesitan dos espacios delante de #
11. Definiciones y llamadas a funciones
12. Documentación de funciones
13. Ejemplo de función
14. Estilo para los TODO: TODO(username)
Resumen de las reglas de programación
1. attach: tratar de evitarlo
2. Funciones: utilizar stop() para generar mensajes de error
3. Objetos y métodos: tratar de evitar el uso de objetos S4; no mezclar nunca S3 y S4

Nomenclatura
- Nombres de ficheros
  
  Los nombres de ficheros deben tener la extensión .R y, por supuesto, ser significativos.
  BIEN: predict_ad_revenue.R
  MAL: foo.R
- Identificadores
  
  No usar guiones bajos ( _ ) o guiones ( - ) en los identificadores. Los identificadores deben asignarse de acuerdo con los siguientes criterios: Los nombres de variables deben ser palabras y letras en minúscula separadas por puntos (.); los nombres de funciones deben ser palabras con su primera letra en mayúsculas y, las demás, en minúsculas y no se usarán puntos para separarlas (ejemplo: CapWords); para las constantes se seguirá la misma convención que para las funciones aunque se utilizará el prefijo k.
  - variable.name
    BIEN: avg.clicks
    MAL: avg_Clicks , avgClicks
  - FunctionName
    BIEN: CalculateAvgClicks
    MAL: calculate_avg_clicks , calculateAvgClicks
    Usa verbos como nombres de funciones.
    Excepción: al trabajar con objetos, el nombre de la función (constructor) y la clase deben coincidir (p.e., lm).
  - kConstantName
Sintaxis
- Longitud de línea
  
  No más de 80 caracteres.
- Indentación
  
  Usar dos espacios para indentar. Nunca mezclar espacios y tabuladores.
  Excepción: cuando la línea se corte dentro de unos paréntesis, hay que alinear la línea seguiente con el primer caracter dentro del los paréntesis.
- Espaciado
  
  Usar espacios alrededor de todos los operadores binarios (=, +, -, <-, etc.).
  Excepción: los espacios alrededor de = son opcionales en las llamadas a una función.
  
  Usar espacios siempre después de las comas, pero nunca antes de ellas.
  BIEN:
```
tabPrior <- table(df[df$daysFromOpt < 0, "campaignid"])
total <- sum(x[, 1])
total <- sum(x[1, ])
```
  MAL:
```
tabPrior <- table(df[df$daysFromOpt<0, "campaignid"])  # Needs spaces around '<'
tabPrior <- table(df[df$daysFromOpt < 0,"campaignid"])  # Necesita un espacio tras la coma
tabPrior<- table(df[df$daysFromOpt < 0, "campaignid"])  # Necesita un espacio antes de <-
tabPrior<-table(df[df$daysFromOpt < 0, "campaignid"])  # Necesita espacios alrededor de <-
total <- sum(x[,1])  # Necesita espacio después de la coma
total <- sum(x[ ,1])  # Necesita un espacio después de la coma, no antes
```
  Usa un espacio delante del paréntesis izquierdo, salvo en llamadas a funciones.
  BIEN:
  if (debug)
  MAL:
  if(debug)
  El espacio adicional en una línea (más de uno en una fila) es permisible si mejora la alineación del código.
```
plot(x    = xCoord,
     y    = dataMat[, makeColName(metric, ptiles[1], "roiOpt")],
     ylim = ylim,
     xlab = "dates",
     ylab = metric,
     main = (paste(metric, " for 3 samples ", sep="")))
```
  No usar espacios alrededor de código en paréntesis o corchetes.
  Excepción: Usar espacio siempre antes de una coma.
  BIEN:
```
if (debug)
x[1, ]
```
  MAL:
```
if ( debug )  # No hay que colocar espacios alrededor de "debug"
x[1,]  # Hace falta un espacio tras la coma
```
- Llaves
  
  Una llave nunca se abre en una línea nueva; sin embargo, siempre se cierran en una línea nueva. Las llaves pueden omitirse cuando encierren una única expresión; sin embargo, esta regla debe seguirse de manera consistente.
```
if (is.null(ylim)) {
  ylim <- c(0, 0.06)
}
```
  xor (no los dos a la vez)
```
if (is.null(ylim))
  ylim <- c(0, 0.06)
```
  Hay que comenzar el cuerpo de un nuevo bloque en una línea nueva.
  MAL:
  if (is.null(ylim)) ylim <- c(0, 0.06)
  if (is.null(ylim)) {ylim <- c(0, 0.06)}
- Asignaciones
  
  Usar <-, no =, para realizar asignaciones.
  BIEN:
  x <- 5 MAL:
  x = 5
- Puntos y comas
  
  No terminar las líneas con puntos y comas. No utilizar puntos y comas para escribir más de una expresión en la misma línea. Nótese que los puntos y comas no son necesarios y que se omiten por consistencia con otras guías de estilo de Google.
Organización
- Distribución general y organización
  
  Si todos siguen los mismos proncipios, podremos leer y entender el código de los demás más rápidamente.
  1. Copyright
  2. Autor
  3. Descripción del fichero, incluyendo la finalidad del programa, sus entradas y sus salidas
  4. Comandos source() y library()
  5. Definición de las funciones
  6. Resto del código, si es aplicable (p.e., print, plot)
  Los tests unitarios deberían incluirse en un fichero aparte llamado originalfilename_unittest.R.
- Comentarios
  
  Usa comentarios en el código. Las líneas que consistan en comentarios deben comenzar por # seguido de un espacio.
  
  Los comentarios breves pueden ubicarse tras el código, separados de éste por dos espacios, un # y un espacio más.
```
# Crear histograma de frecuencias de campañas según porcentaje del presupuesto
hist(df$pctSpent,
     breaks = "scott",  # método para elegir el número de buckets
     main   = "Histogram: fraction budget spent by campaignid",
     xlab   = "Fraction of budget spent",
     ylab   = "Frequency (count of campaignids)")
```
- Funciones: definiciones y llamadas
  
  La definición de las funciones debe contener primero los argumentos sin valores por defecto.
  
  En la definición y llamadas a funciones se permiten múltiples argumentos por línea. Las nuevas líneas sólo deben separar asignaciones.
  
  BIEN:
```
PredictCTR <- function(query, property, numDays,
                       showPlot = TRUE)
```
  MAL:
```
PredictCTR <- function(query, property, numDays, showPlot =
                       TRUE)
```
  Idealmente, las pruebas unitarias deberían servir como ejemplo de llamadas a funciones (para rutinas de librerías compartidas).
- Documentación de funciones
  
  Las funciones deberían tener una sección de comentarios inmediatamente debajo de la línea de definición de la función. Tales comentarios deberían consistir en una frase que definiese la función, una lista de los argumentos de la función precedida por Args: con una descripción de cada uno de ellos, incluido su tipo y una descripción del valor devuelto por la función precedido por Returns:. Los comentarios deberían ser lo suficientemente descriptivos como para que un usuario pudiera utilizar la función sin tener que leer su código.
- Ejemplo de función
```
CalculateSampleCovariance <- function(x, y, verbose = TRUE) {
  # Computes the sample covariance between two vectors.
  #
  # Args:
  #   x: One of two vectors whose sample covariance is to be calculated.
  #   y: The other vector. x and y must have the same length, greater than one,
  #      with no missing values.
  #   verbose: If TRUE, prints sample covariance; if not, not. Default is TRUE.
  #
  # Returns:
  #   The sample covariance between x and y.
  n <- length(x)
  # Error handling
  if (n <= 1 || n != length(y)) {
    stop("Arguments x and y have invalid lengths: ",
         length(x), " and ", length(y), ".")
  }
  if (TRUE %in% is.na(x) || TRUE %in% is.na(y)) {
    stop(" Arguments x and y must not have missing values.")
  }
  covariance <- var(x, y)
  if (verbose)
    cat("Covariance = ", round(covariance, 4), ".\n", sep = "")
  return(covariance)
}
```
- Estilo para los TODO
  
  Usa un estilo consistente para los TODO en el código.
  
  TODO(username): Descripción de lo que tiene que hacerse
Lenguaje
- Attach
  
  El uso de attach puede producir muchos errores. Evítalo.
- Funciones
  
  Usar stop() para lanzar mensajes de error.
- Objects and Methods
  
  El lenguaje S tiene dos tipos de sistemas de clases, S3 y S4, disponibles en R. Los métodos S3 son más interactivos y flexibles, mientras que los S4 son más formales y rigurosos. (Para una ilustración de los dos sistemas, véase "Programmer's Niche: A Simple Class, in S3 and S4" in R News 4/1, 2004, pgs. 33 - 36: http://cran.r-project.org/doc/Rnews/Rnews_2004-1.pdf por Thomas Lumley.)
  
  Usa objetos y objetos S3 a no ser que exista una razón poderosa para usar los del tipo S4. Una justificación para usar objetos S4 sería la de poder manipularlos directamente desde C++. Para usar métodos S4, sería poder despachar en función de dos argumentos.
  
  Evita mezclar métodos S3 y S4: los métodos S4 ignoran la herencia de los S3 y a la inversa.
Excepciones

Las convenciones expresadas más arriba deberían ser seguidas de no haber un buen motivo para seguir otro criterio: por ejemplo, al usar código antiguo o de terceras partes.
Consideraciones finales

Usa el sentido común y SÉ CONSISTENTE.

Si estás editando código, tómate unos minutos para mirar alrededor y determinar cuál es el estilo del código. Si los autores originales usaban espacios alrededor de sus comandos if , deberías hacerlo tambén.

Si sus comentarios tienen cajas o estrellas alrededor, úsalas también.

El objetivo de tener un código de estilo es el usar un vocabulario común para poder concentrarse en lo que estás diciendo más que en cómo lo estás diciendo. Al presentar unas reglas globales de estilo intentamos que se use un vocabulario común. Pero el estilo local es importante. Si el código que añades a un fichero sigue una convención distinta, la discontinuidad provocará el rechazo de quienes lo hereden. Trata de evitar eso.

Bien, y una vez finalizada la tarea sobre cómo escribir código, podemos comenzar a escribirlo, que es mucho más interesante. ¡Disfrutémoslo!
Referencias
http://www.maths.lth.se/help/R/RCC/ - R Coding Conventions
http://ess.r-project.org/ - Para usuarios de emacs
http://google-styleguide.googlecode.com/svn/trunk/google-r-style.html - Guía de estilo de R de Google (en inglés)
Notas

Esta guía de estilo de R es una traducción literal de la de Google que he tomado la libertad de traducir para referencia y discusión propia y ajena. Datanalytics se hace responsable de todos los errores de traducción. Por otra parte, no se arroga (explícita o implícitamente) ningún tipo de derecho de copiright, autoría o similares: todos pertenecen a Google.

Guía de estilo de R (de Google)

Resumen de las reglas de estilo

Resumen de las reglas de programación

Nomenclatura

Nombres de ficheros

Identificadores

Sintaxis

Longitud de línea

Indentación

Espaciado

Llaves

Asignaciones

Puntos y comas

Organización

Distribución general y organización

Comentarios

Funciones: definiciones y llamadas

Documentación de funciones

Ejemplo de función

Estilo para los TODO

Lenguaje

Attach

Funciones

Objects and Methods

Excepciones

Consideraciones finales

Referencias

Notas