Código legible en R

# Código legible en R
## 6 consejos simples y prácticos para escribir mejor código
###

---

```
#> 
#>  ----- 
#> Hola a todas y todos! 
#>  ------ 
#>     \   ^__^ 
#>      \  (oo)\ ________ 
#>         (__)\         )\ /\ 
#>              ||------w|
#>              ||      ||
```
]

.pull-right[
Analytics Developer
 
(<svg aria-hidden="true" role="img" viewBox="0 0 581 512" style="height:1em;width:1.13em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:white;overflow:visible;position:relative;"><path d="M581 226.6C581 119.1 450.9 32 290.5 32S0 119.1 0 226.6C0 322.4 103.3 402 239.4 418.1V480h99.1v-61.5c24.3-2.7 47.6-7.4 69.4-13.9L448 480h112l-67.4-113.7c54.5-35.4 88.4-84.9 88.4-139.7zm-466.8 14.5c0-73.5 98.9-133 220.8-133s211.9 40.7 211.9 133c0 50.1-26.5 85-70.3 106.4-2.4-1.6-4.7-2.9-6.4-3.7-10.2-5.2-27.8-10.5-27.8-10.5s86.6-6.4 86.6-92.7-90.6-87.9-90.6-87.9h-199V361c-74.1-21.5-125.2-67.1-125.2-119.9zm225.1 38.3v-55.6c57.8 0 87.8-6.8 87.8 27.3 0 36.5-38.2 28.3-87.8 28.3zm-.9 72.5H365c10.8 0 18.9 11.7 24 19.2-16.1 1.9-33 2.8-50.6 2.9v-22.1z"/></svg> package developer) en <img src="img/logo-kantar.png" width=120>

🥐 ☕ amante del pan y el café.
]

???

---

*  Mantenemos un ecosistema de más de 10 paquetes en **R**.
--

* Desarrollamos código de forma colaborativa en un equipo de 4 integrantes.
--

* Otros equipos de la organización pueden ver tu código.
--

* Los paquetes son usados para generar cerca de 10,000 análisis al mes.

**Seguir las buenas prácticas de escritura de código se vuelve imperativo**

---

 
 
.pull-left[
 
 
 
 
 Esta keynote está basada en el libro **The Art of Readable Code** (2012) de Dustin Boswell y Trevor Foucher.
]

.pull-right[
<center>
<img src="img/book-cover.jpeg" alt="" width="300" height="400"></img>
</center>
]

---

# El Teorema fundamental de la legibilidad

> El código debe ser escrito para minimizar el tiempo que le tomaría a alguien más entenderlo. 👩‍💻

**¿Y si yo soy el único que lee el código que escribo?**

---

## 1. Estética

---
class: middle

---

> Un buen código debe ser "agradable a la vista".

Específicamente, hay un par de principios que deberíamos seguir:

- Utilizar un diseño consistente, con patrones a los que el lector pueda acostumbrarse.

- Si es posible, apegarse a lo estándares de la comunidad de R, recomendable **The tidyverse style guide** (https://style.tidyverse.org).

---

¡Trivia!

```r
max_by = function(data,var,by)
  data %>% group_by(by) %>% summarise(maximum=max(var,na.rm=T))
```

```r
# Bien :)
max_by <- function(data, var, by) {
 data %>%
 group_by(by) %>%
 summarise(maximum = max(var, na.rm = TRUE))
}
```

---

## Ideas clave
* Todo el mundo prefiere leer un código que sea **estéticamente agradable**. Si "formateas" tu código de forma coherente y con sentido, lo harás **más fácil y rápido de leer**.
--

* Un **estilo consistente** es más importante que el estilo "correcto"

--
* Hacer check de linternas sobre los scripts (paquete)

---

## 2. Da información al nombrar

---

```r
obtenDatos <- function() {
 ...
}
```

--
¿Va a descargar datos? ¿Los datos serán un `data.frame`, un `tibble` o un `data.table`?
 
--

```r
getTreeSize <- function() {
 ...
}
```

¿Qué queremos del árbol realmente?

Nombres como `heightTree()` o `numNodesTree()` dejarían más claro la intención de lo que significa el tamaño del árbol.

---

| Palabras | Alternativa |
| -------- | ----------- |
|  send    | search, extract, distribute |
|  find    | search, extract, locate, recover |
|  start   | create, begin, open |
|  make    | create, set-up, build, generate, add |

---

# Nombres temporales

Nombres como `temp`, `val`, y `x` usualmente significan cosas como “no pude pensar en otro nombre”.

```r
norma_euclideana <- function(v) {
 final <- 0
 for(i in seq_along(v)) {
 final <- final + v[i] ^ 2
 }
 sqrt(final)
}
```

La única información que aporta la variable final, es que será usada para retornar el valor final dentro de un cálculo.

`suma_cuadrado <- suma_cuadrado + v[i]^2`

---

Pensemos en esta línea

`final <- final + v[i]`

el bug sería más fácil de identificar con...

`suma_cuadrado <- suma_cuadrado + v[i]`

¿Dónde está el cuadrado en suma cuadrado?

---

Pueden haber excepciones...

```r
if (right < left) {
 temp <- right
 right <- left
 left <- temp
}
```

---

## El nombre es un comentario

```r
temp <- calcularPrecioUSD(casa_mts, casa_num_cuartos)
valor_final <- temp * tasa_usd_a_pesos
```

--
mejor...

```r
precio_casa_usd <- calcularPrecioUSD(casa_mts, casa_num_cuartos)
precio_casa_pesos <- precio_casa_usd * tasa_usd_a_pesos
```

---

## ¿Qué tan grande puede ser un nombre?

¡Trivia!

---

## Ideas clave

* Los mejores nombres son aquellos **libres de ambigüedades**

* Todos los nombres **son comentarios**. Da información al nombrar.

* Usa **nombres más largos** para **scopes grandes**.

---

## 3. Saber que comentar

---

## ¿Qué instructivo valdría más la pena leer?

---

## Qué no comentar

```r
# Suma a y b
suma <- function(a, b) {
 a + b
}
```

```r
# Estima los coeficientes del modelo de regresión
coeficientes <- estimaCoeficientesModelo(...)
```

```r
a <- c("Item1.13xrs2", "Item2.#@ ", "Item3.zszc32")

# Extrae el texto antes del punto
sub("\\..*", "", a)
```

---

## Graba tus pensamientos

### Comentarios "del director"

```r
# Sorprendentemente, un árbol binario fue un 40% más rápido que una tabla hash
# para estos datos. El coste de calcular un hash era mayor que las
# comparaciones izquierda/derecha.
```

```r
# Esta heurística puede pasar por alto algunas palabras
# No pasa nada; resolver esto al 100% es difícil.
```

```r
# Esta función está quedando compleja. Quizá deberíamos crear otra función
# 'limpiaTabla()' para ayudar a refactorizar esto.
```

---

## Comenta los pormenores de tu código

### Usa "marcadores"

```r
# TODO: usa un algoritmo más rápido
```

```r
# TODO: utilizar un formato de imágen distinto a JPEG
```

| Marcador | Significado |
| -------- | ----------- |
|  TODO    | Cosas que puedes hacer en un futuro |
|  FIXME    | Código que necesita ser reparado |
|  HACK   | Una solución poco elegante |
|  XXX    | Encontraste un problema mayor! |

---

---

### Comentarios más generales (big picture)

```r
#' A set of functions which take two sets or bag of words and measure their
#' similarity or dissimilarity.
```

```r
#' This function retrieves the matches for a single document from an \code{lsh_buckets}
#' object created by \code{\link{lsh}}.
```

```r
# Este archivo contiene funciones de ayuda para hacer la interfaz de la Shiny más conveniente
# para nuestros usuarios finales. 
```

---

### Supera el bloqueo del escritor

```r
# Híjole, esto se va a poner horrible si hay duplicados en el vector!!!
```

⬇️

```r
# Cuidado: este código no está contemplando valores duplicados
```

---

## 4.  Haz el control de flujo más sencillo de leer

---

# Idea clave

> Haz todas tus condicionales, loops, o cualquier otro control de flujo tan "natural" como sea posible. 🍈 🍌 🍓

---

```r
if (length(x) >= 10)
```

```r
if (10 <= length(x))
```

Si tienes al menos 18 años.

Si 18 años es menor que tu edad actual. 😕

---

```r
if (a == b) {
  # Caso uno
} else {
  # Caso dos
}
```

```r
if (a != b) {
  # Caso dos
} else {
  # Caso uno
}
```

---

## Minimiza los bloques anidados

.pull-left[
 
 ```r
 get_data <- function(config, output) {
 if (is_config_ok(config)) {
 if (connection_works(config)) {
 data <- parse_data()
 if (has_right_format(data)) {
 write_data(data, output)
 return(TRUE)
 } else {
 return(FALSE)
 }
 } else {
 stop("Problem with connection")
 }
 } else {
 stop("Wrong config data")
 }
 }
 ```
]

.pull-right[
 
 ```r
 get_data <- function(config, output) {
 if (bad_config(config)) {
 stop("Bad config")
 }
 
 if(!connection_works(config)) {
 stop("Can't access to connection")
 }
 
 data <- parse_data()
 if (!has_right_format(data)) {
 return(FALSE)
 }
 
 write_data(data, output)
 TRUE
 
 }
 ```
]

---

## Rompe grandes expresiones

---

## Usa variables explicativas

```r
checkmate::assertFlag(!is.null(findBucket(key)) || !isOccupied(findBucket(key)))
```

👍

```r
bucket <- findBucket(key)
if(!is.null(bucket)) checkmate::assertFlag(!isOccupied(bucket))
```

---

```r
if (has_valid_id(str_extract(get_user_id(x), "\\d"))) {
  ...
}
```

👍

```r
user_id <- get_user_id(x)
is_ID_valid <- has_valid_id(str_extract(user_id, "\\d"))
if (is_ID_valid) {
 ...
}
```

---

## Ideas clave

* Expresiones grandes son difíciles de entender, rómpelas en **partes más pequeñas**

* Usa **variables explicativas** que resuman expresiones lógicas

---

# 5.  Extrae el subproblema

---

1. Mira una función o bloque de código y pregúntate: "¿Cuál es el objetivo (alto nivel) de este código?"

2. Para cada línea de código, pregúntate: "¿Está trabajando directamente para ese objetivo? ¿O está resolviendo un subproblema no relacionado necesario para alcanzarlo?"

3. Si hay suficientes líneas que resuelven un subproblema no relacionado, extrae ese código en una función separada.

---

```r
# Return which element of 'list_coords' is closest to the given latitude/longitude.
# Models the Earth as a perfect sphere.
findClosestLocation <- function(lat, lng, list_coords) {
 closest_dist <- .Machine$double.xmax
 for(i in seq(list_coords)) {
 # Convert both points to radians.
 lat_rad <- lat * pi / 180
 lng_rad <- lat * pi / 180
 lat2_rad <- list_coords[[i]]$lng * pi / 180
 lng2_rad <- list_coords[[i]]$lng * pi / 180
 
 # Use the "Spherical Law of Cosines" formula.
 distance <- acos(
 sin(lat_rad) * sin(lat2_rad) +
 cos(lat_rad) * cos(lat2_rad) * cos(lng2_rad - lng_rad)
 )

if(distance < closest_dist) {
 closest <- list_coords[[i]]
 closest_dist <- distance
 }
 }
 return(closest)
}
```

---

```r
convert2rad <- function(x) {
 x * pi / 180
}
```

```r
spherical_distance <- function (lat1, lng1, lat2, lng2) {
lat1_rad <- convert2rad(lat1)
lng1_rad <- convert2rad(lng1)
lat2_rad <- convert2rad(lat2)
lng2_rad <- convert2rad(lng2)
# Use the "Spherical Law of Cosines" formula.
return(acos(
 sin(lat_rad) * sin(lat2_rad) +
 cos(lat_rad) * cos(lat2_rad) * cos(lng2_rad - lng_rad)))
}
```

---

```r
findClosestLocation <- function(lat, lng, list_coords) {
 closest_dist <- .Machine$double.xmax
 for(i in seq(list_coords)) {
 distance <- spherical_distance(lat, lng, list_coords[[i]]$lat, list_coords[[i]]$lng)
 if(distance < closest_dist) {
 closest <- list_coords[[i]]
 closest_dist <- distance
 }
 }
 return(closest)
}
```

¡Trivia!

---

## 6. Una tarea a la vez

---

---

Fuente: *The Art Of Readable Code*

---

```r
vote_changed <- function(old_vote, new_vote) {
 score <- get_score()

if (new_vote != old_vote) {
 if (new_vote == "up") {
 score <- score + ifelse(old_vote == "down", 2, 1)
 } else if (new_vote == "down") {
 score <- score - ifelse(old_vote == "up", 2, 1)
 } else if (new_vote == "") {
 score <- score + ifelse(old_vote == "up", -1, 1)
 }
 }

set_score(score)
}
```

---

```r
vote_value <- function(vote) {
 switch (vote,
 "up" = 1,
 "down" = -1,
 0
 )
}
```

la siguiente función requiere menor esfuerzo físico:

```r
vote_changed <- function(old_vote, new_vote) {
 score <- get_score()
 
 score <- score - vote_value(old_vote) # Remove the old vote
 score <- score + vote_value(new_vote) # Add the new vote
 
 set_score(score)
}
```

---

## Para finalizar

* Estos consejos son **extrapolables** a cualquier lenguaje.

* Piensa en el **teorema de la legibilidad** cuando escribas nuevo código.

* **Lee código** de alguien más. Los paquetes populares del tidyverse son un buena guía.

* Siempre habrá **excepciones**, pero asegúrate que sea una **buena excusa**.

---

# ¡Gracias!