03_estilo.Rmd

# Guía de estilo {#estilo}

Así como en el español existen reglas ortográficas, la escritura de códigos en R también tiene unas reglas que se recomienda seguir para evitar confusiones. Tener una buena guía de estilo es importante para que el código creado por usted sea fácilmente entendido por sus lectores [@rpackages]. No existe una única y mejor guía de estilo para escritura en R, sin embargo aquí vamos a mostrar unas sugerencias basadas en la guía llamada [The tidyverse style guidee](https://style.tidyverse.org/).

## Nombres de los archivos
Se sugiere que el nombre usado para nombrar un archivo tenga sentido y que termine con extensión ".R". A continuación dos ejemplos de como nombrar bien y mal un archivo.

- Mal: `analisis_icfes.R`
- Bien: `ju89HR56_74.R`

## Nombres de los objetos
Se recomienda usar los símbolos `_` dentro de los nombres de objetos. 

- Para las variables es preferible usar letras minúsculas (`pesomaiz` o `peso_maiz`) o utilizar la notación camello iniciando en minúscula (`pesoMaiz`). 
- Para las funciones se recomienda usar la notación camello iniciando todas la palabras en mayúscula (`PlotRes`). 
- Para los nombres de las constantes se recomienda que inicien con la letra k (`kPrecioBus`).

## Longitud de una línea de código
Se recomienda que cada línea tenga como máximo 80 caracteres. Si una línea es muy larga se debe cortar siempre por una coma.

## Espacios
Use espacios alrededor de todos los operadores binarios (=, +, -, <-, etc.). Los espacios alrededor del símbolo `=` son opcionales cuando se usan para ingresar valores dentro de una función. Así como en español, nunca coloque espacio antes de una coma, pero siempre use espacio luego de una coma. A continuación ejemplos de buenas y malas prácticas.

```{r, eval=F}
tab <- table(df[df$days < 0, 2])  # Bien
tot <- sum(x[, 1])                # Bien
tot <- sum(x[1, ])                # Bien
tab <- table(df[df$days<0, 2])    # Faltan espacios alrededor '<' 
tab <- table(df[df$days < 0,2])   # Falta espacio luego de coma
tab <- table(df[df$days < 0 , 2]) # Sobra espacio antes de coma
tab<- table(df[df$days < 0, 2])   # Falta espacio antes de '<-'
tab<-table(df[df$days < 0, 2])    # Falta espacio alrededor de '<-'
tot <- sum(x[,1])                 # Falta espacio luego de coma
tot <- sum(x[1,])                 # Falta espacio luego de coma
```

Otra buena práctica es colocar espacio antes de un paréntesis excepto cuando se llama una función.

```{r, eval=F}
if (debug)    # Correcto
if(debug)     # Funciona pero no se recomienda
colMeans (x)  # Funciona pero no se recomienda
```

Espacios extras pueden ser usados si con esto se mejora la apariencia del código, ver el ejemplo siguiente.

```{r, eval=F}
plot(x    = x.coord,
     y    = data.mat[, MakeColName(metric, ptiles[1], "roiOpt")],
     ylim = ylim,
     xlab = "dates",
     ylab = metric,
     main = (paste(metric, " for 3 samples ", sep = "")))
```

No coloque espacios alrededor del código que esté dentro de paréntesis `( )` o corchetes `[ ]`, la única excepción es luego de una coma, ver el ejemplo siguiente.

```{r, eval=F}
if (condicion)    # Correcto 
x[1, ]            # Correcto
if ( condicion )  # Sobran espacios alrededor de condicion
x[1,]             # Se necesita espacio luego de coma
```

Los signos de agrupación llaves `{ }` se utilizan para agrupar bloques de código y se recomienda que nunca una llave abierta `{` esté sola en una línea; una llave cerrada `}` si debe ir sola en su propia línea. Se pueden omitir las llaves cuando el bloque de instrucciones esté formado por una sola línea pero esa línea de código NO debe ir en la misma línea de la condición. A continuación dos ejemplos de lo que se recomienda.

```{r, eval=F}
if (is.null(ylim)) {                     # Correcto
  ylim <- c(0, 0.06)
}

if (is.null(ylim))                       # Correcto
  ylim <- c(0, 0.06)

if (is.null(ylim)) ylim <- c(0, 0.06)    # Aceptable

if (is.null(ylim))                       # No se recomienda
{        
  ylim <- c(0, 0.06)
}
	
if (is.null(ylim)) {ylim <- c(0, 0.06)}
# Frente a la llave { no debe ir nada
# la llave de cierre } debe ir sola
```

La sentencia else debe ir siempre entre llaves `} {`, ver el siguiente ejemplo.

```{r, eval=F}
if (condition) {         
  one or more lines
} else {                 # Correcto
  one or more lines
}


if (condition) {         
  one or more lines
}
else {                   # Incorrecto
  one or more lines
}


if (condition)           
  one line
else                     # Incorrecto
  one line
```

## Asignación en R
En R se pueden hacer asignación de varias formas, a continuación se presentan los operadores disponibles para tal fin.

- `<-` este es el operador de asignación a izquierda, es el más usado y recomendado.
- `->` este es el operador de asignación a derecha, no es frecuente su uso.
- `=` el símbolo igual sirve para hacer asignaciones pero __NO__ se recomienda usarlo.
- `<<-` este es un operador de asignación global y sólo debe ser usado por usuarios avanzados.

Para una explicación más detallada sobre el símbolo de asignación se recomienda visitar este [enlace](http://www.win-vector.com/blog/2016/12/the-case-for-using-in-r/).

### Ejemplo {-}
Almacene los valores 5.3, 4.6 y 25 en los objetos `a`, `b` y `age` respectivamente, use diferentes símbolos de asignación.

Para hacer lo solicitado se podría usar el siguiente código.

```{r}
a <- 5.3 # Recomended
4.6 -> b # It is not usual
age = 25 # Not recomended
```

```{block2, type='rmdimportant'}
Aunque una asignación se puede hacer de tres formas diferentes, se recomienda sólo usar el símbolo `<-`.
```

Para realizar asignaciones se recomienda usar el símbolo `<-`, el símbolo de igualdad `=` no se recomienda usarlo para asignaciones.

```{r, eval=F}
x <- 5  # Correcto
x = 5   # No recomendado
```

## Punto y coma
No se recomienda colocar varias instrucciones separadas por `;` en la misma línea, aunque funciona dificulta la revisión del código.

```{r, eval=F}
n <- 100; y <- rnorm(n, mean=5); hist(y)  # No se recomienda

n <- 100                                  # Correcto
y <- rnorm(n, mean=5)
hist(y)
```
A pesar de la anterior advertencia es posible que en este libro usemos el `;` en algunas ocasiones, si lo hacemos es para ahorrar espacio en la presentación del código.