Guía del Google I Estilo

Guía del Google I Estilo

R es un lenguaje de programación de alto nivel utilizado principalmente para computación y gráficos estadísticos. El objetivo de la Guía de Estilo R programación es hacer que nuestro código R más fácil de leer, compartir y verificar. Las siguientes reglas fueron diseñadas en colaboración con toda la comunidad de R usuario en Google.

• Resumen: R Reglas Estilo

1. Nombres de archivo : fin en .R

2. Identificadores : variable.name , NombreFunción , kConstantName

3. Longitud de la línea : 80 caracteres como máximo

4. Sangría : dos espacios, sin pestañas

5. Espaciado

6. Curly Tirantes : primero en la misma línea, la última en la propia línea de

7. Asignación : usar <- , no =

8. Punto y coma : No utilice los

9. Disposición general y pedidos

10. Comentando Directrices : todos los comentarios comienzan con # seguido de un espacio; comentarios en línea necesitan dos espacios antes de la #

11. Definiciones de función y Llamadas

12. Documentación de las funciones

13. Ejemplo de la función

14. TODO Estilo : TODO (nombre de usuario)

• Resumen: R Reglas del idioma

1. adjuntar : evitar su uso

2. Funciones : los errores deben ser levantadas utilizando stop ()

3. Objetos y Métodos : evitar los objetos y métodos cuando sea posible S4; Nunca mezcle S3 y S4

1. Notación y Naming

o Nombres de archivo

Nombre de los archivos terminan en .R y, por supuesto, ser significativa.

BUENO: predict_ad_revenue.R

BAD: foo.R

o Identificadores

No use guiones bajos ( _ ) o guiones ( - ) en los identificadores. Identificadores deben ser nombradas de acuerdo a los siguientes convenios. Los nombres de variables deben tener todas las letras y palabras separadas con puntos minúsculas ( . ); nombres de las funciones tienen letras mayúsculas iniciales y sin puntos (CapWords); constantes se nombran como funciones, pero con una inicial k .

 variable.name

BUENO: avg.clicks

BAD: avg_Clicks , avgClicks

 NombreFunción

BUENO: CalculateAvgClicks

BAD: calculate_avg_clicks , calculateAvgClicks

. Haga nombres de función verbos Excepción: Cuando se crea un objeto clasificada, el nombre de la función (constructor) y la clase deben coincidir (por ejemplo, lm).

 kConstantName

2. Sintaxis

o Longitud de la línea

La longitud máxima de la línea es de 80 caracteres.

o Sangría

Cuando sangría su código, use dos espacios. Nunca utilice pestañas o mezclar las fichas y espacios. Excepción: Cuando se produce un salto de línea dentro de paréntesis, alinee la línea envuelto con el primer carácter dentro del paréntesis.

o Espaciado

Espacios Colocar alrededor de todos los operadores binarios ( = , + , - , <- , etc). Excepción: Los espacios alrededor = 's son opcionales al pasar parámetros en una llamada a la función.

No coloque un espacio antes de una coma, pero siempre coloque uno después de una coma. BUENO:

tabPrior <- mesa (df [df $ daysFromOpt <0, "campaignId"])

Total <- sum (x [, 1])

total de <- suma (x [1,])

BAD:

tabPrior <- mesa (df [df $ daysFromOpt <0, "campaignId"]) # Necesidades espacios alrededor de '<'

tabPrior <- mesa (df [df $ daysFromOpt <0, "campaignId"]) # necesita un espacio después de la coma

tabPrior <- mesa (df [df $ daysFromOpt <0, "campaignId"]) # necesita un espacio antes de <-

tabPrior <-table (df [df $ daysFromOpt <0, "campaignId"]) # Necesidades espacios alrededor <-

Total <- sum (x [, 1]) # necesita un espacio después de la coma

Total <- sum (x [, 1]) # necesita un espacio después de la coma, no antes

Ponga un espacio antes paréntesis izquierdo, excepto en una llamada de función.

BUENO: if (debug)

BAD: if (debug)

Espaciado extra (es decir, más de un espacio en una fila) está bien si mejora la alineación de los signos de igual o flechas ( <- ).

plot (x = xCoord,

y = Datamat [, makeColName (métricas, ptiles [1], "roiOpt")],

ylim = ylim,

XLab = "fechas",

ylab = métrica,

main = (pasta (métrica, "por 3 muestras", sep = "")))

No ponga espacios alrededor de código entre paréntesis o corchetes. Excepción: Coloque siempre un espacio después de una coma.

BUENO:

if (debug)

x [1,]

BAD:

if (depuración) # No hay espacios alrededor de depuración

x [1,] # necesita un espacio después de la coma

o Curly Tirantes

Una llave de apertura nunca debe ir en su propia línea; una llave de cierre debe ir siempre en su propia línea. Se puede omitir las llaves cuando un bloque se compone de una sola declaración; sin embargo, debe constantemente ya sea usar o no usar llaves para bloques de instrucciones individuales.

if (is.null (ylim)) {

ylim <- c (0, 0.06)

}

xor (pero no ambos)

if (is.null (ylim))

ylim <- c (0, 0.06)

Comience siempre el cuerpo de un bloque en una línea nueva.

BAD: ylim <if (is.null (ylim)) - c (0, 0,06) si (is.null (ylim)) {ylim <- c (0, 0,06)}

o Asignación

Utilice <- , no = , para la asignación.

BUENO: x <- 5

BAD: x = 5

o Punto y coma

No termine sus líneas con punto y coma o utilice punto y coma para poner más de un comando en la misma línea. (Punto y coma no son necesarios, y se omiten para mantener la coherencia con otras guías de estilo de Google.)

3. Organización

o Disposición general y pedidos

Si todo el mundo utiliza el mismo orden en general, vamos a ser capaces de leer y entender los scripts del otro más rápido y más fácilmente.

1. Declaración de nota de copyright,

2. Autor comentario

3. Descripción del archivo comentario, incluyendo efectos de los programas, entradas y salidas

4. fuente () y biblioteca () declaraciones

5. Las definiciones de funciones

6. Sentencias ejecutadas, en su caso (por ejemplo, impresión , parcela )

Las pruebas unitarias deben ir en un archivo separado llamado originalfilename_unittest.R .

o Comentando Directrices

Comentario el código. Líneas comentadas enteras deben comenzar con # y un espacio.

Los comentarios cortos se pueden colocar después de código precedido por dos espacios, # , y luego un espacio.

# Crear histograma de frecuencia de las campañas por el presupuesto pct gastado.

hist (df $ pctSpent,

descansos = "scott", # método para elegir el número de cubos

main = "Histograma: presupuesto fracción gastado por campaignId",

xlab = "Fracción del presupuesto gastado",

ylab = "Frecuencia (recuento de campaignids)")

o Definiciones de función y Llamadas

Las definiciones de funciones primero deben enumerar argumentos sin valores predeterminados, seguidos de los que tienen valores por defecto.

En ambas definiciones de funciones y llamadas a funciones, se permiten múltiples argumentos por línea; saltos de línea sólo se permite entre las asignaciones.

BUENO:

PredictCTR <- función (consulta, la propiedad, numDays,

showPlot = TRUE)

BAD:

PredictCTR <- function (consulta, la propiedad, numDays, showPlot =

TRUE)

Idealmente, las pruebas unitarias deben servir como llama a la función de la muestra (para las rutinas de bibliotecas compartidas).

o Documentación de las funciones

Funciones deben contener una sección de comentarios inmediatamente por debajo de la línea de definición de la función. Estos comentarios deben consistir en una descripción de una sola frase de la función;una lista de argumentos de la función, denotados por Args: , con una descripción de cada uno (incluyendo el tipo de datos); y una descripción del valor de retorno, que se denota por Devoluciones: . Los comentarios deben ser descriptivos basta con que una persona que llama puede usar la función sin leer cualquiera de código de la función.

o Ejemplo de la función

CalculateSampleCovariance <- function (x, y, verbose = TRUE) {

# Calcula la covarianza muestral entre dos vectores.

#

# Args:

# x: Uno de los dos vectores cuya covarianza muestral se va a calcular.

# Y: El otro vector. x e y deben tener la misma longitud, mayor que uno,

# Sin valores faltantes.

# Verbose: Si es verdad, impresiones de la muestra de covarianza; si no, no. El valor predeterminado es TRUE.

#

Devoluciones #:

# La covarianza muestral entre x e y.

n <- longitud (x)

# Gestión de errores

if (n <= 1 || n! = longitud (y)) {

detener ("argumentos x e y tienen longitudes no válidas:",

longitud (x), "y", la longitud (y), ".")

}

if (TRUE% en% is.na (x) || TRUE% en% is.na (y)) {

detener ("argumentos x e y no debe tener valores perdidos.")

}

covarianza <- var (x, y)

if (detallado)

cat ("Covarianza =", redondo (covarianza, 4), ". \ n", sep = "")

retorno (covarianza)

}

o TODO Estilo

Utilice un estilo consistente para TODOs en todo el código. TODO (nombre de usuario): descripción explícita de medidas que deben adoptarse

4. Idioma

o Adjuntar

Las posibilidades de crear errores al usar adjuntar son numerosos. Evítalo.

o Funciones

Los errores deben ser criados usando stop () .

o Objetos y Métodos

El lenguaje S tiene dos sistemas de objetos, S3 y S4, ambos de los cuales están disponibles en métodos R. S3 son más interactivo y flexible, mientras que los métodos S4 son más formal y riguroso. (Para ver una ilustración de los dos sistemas, consulte "Nicho del programador: una clase simple, en S3 y S4" de Thomas Lumley en I Noticias 4.1, 2004, pgs 33 - 36:. http: //cran.r-proyecto. org / doc / rnews / Rnews_2004-1.pdf .)

Use objetos y métodos S3 menos que haya una razón de peso para utilizar objetos o métodos S4. Una justificación primaria para un objeto S4 sería utilizar objetos directamente en código C ++. Una justificación primaria para un genérico / método S4 sería despachar en dos argumentos.

Evite mezclar S3 y S4: métodos ignoran S4 S3 herencia y vice-versa.

5. Excepciones

Las convenciones de codificación descritas anteriormente se deben seguir, a menos que haya una buena razón para hacer lo contrario. Las excepciones incluyen código heredado y modificación de código de terceros.

6. Palabras de despedida

Use el sentido común y ser coherente.

Si va a editar código, tómese unos minutos para mirar el código a tu alrededor y determinar su estilo. Si otras personas utilizan los espacios en torno a sus si cláusulas, usted también debería hacerlo. Si sus comentarios tienen pequeñas cajas de estrellas alrededor de ellos, hacer sus comentarios tienen pequeñas cajas de estrellas alrededor de ellos, también.

El punto de tener pautas de estilo es tener un vocabulario común de codificación que la gente pueda concentrarse en lo que está diciendo, y no en la forma en que usted está diciendo que. Presentamos reglas de estilo globales aquí que la gente sepa el vocabulario. Pero el estilo local también es importante. Si el código que se agrega a un archivo se ve drásticamente diferente del código existente a su alrededor, la discontinuidad lanzará lectores fuera de su ritmo cuando van a leerlo. Trate de evitar esto. Muy bien, basta escribir sobre la escritura de código; el código en sí es mucho más interesante. Divertirse!

...