Código y datos para las ciencias sociales- Parte 5

En las entradas anteriores vimos una introducción del manual Code and Data for the Social Sciences: A Practitioner’s Guide y los capítulos dedicados a automatizar y control de versiones, directorios y claves. Finalizamos esta serie de artículos con los capítulos dedicados a la simplificación y la documentación.

Capítulo 6- Simplificación

1. Simplifica para eliminar redundancias
2. Simplifica para mejorar la claridad
3. En caso contrario, no simplifiques.

La simplificación puede llevarse demasiado lejos. Si una operación que sólo necesita ser ejecutada una vez es fácil de leer, no sería recomendable. Simplificar sin propósito puede conducir a emplear mucho tiempo en casos que  nunca aparecerán en tu trabajo. La simplificación no afecta solamente al código, es relevante en cualquier momento en el que estés repitiendo una operación.

Capítulo 7- Documentación

1. No escribas documentación que no mantendrás
2. El código debería autodocumentarse

Cada vez que tienes más de una representación de la misma información, corres el riesgo de que alguno de las dos entre algún día en conflicto. En el mejor caso, necesitarás trabajar para desentrañar la confusión. En el peor caso, tus resultados serán erróneos o inconsistentes internamente.

El problema de consistencia interna es especialmente grave en el caso de documentación (comentarios, notas, léemes, etc) porque no tienes que mantenerla actualizada para que funcione el código.  Es tentador hacer mejoras del código sin actualizar los comentarios del mismo en paralelo.

Cuando sea posible, debes de escribir tu código para que se autodocumente. Nombra las variables y la estructura del código para guiar al lector a lo largo de las operaciones. Ni incluso los mejores comentarios pueden desenmarañar un código confuso. Al igual que la simplificación, estos principios no se aplican exclusivamente al código sino que subyacen en varios de los capítulos anteriores.

Los comentarios pueden ser usados para aclarar algo que es correcto pero que a primera vista puede parecer erróneo. También para prevenir comportamientos no deseados. Sin embargo, si hay alguna acción que realmente quieres evitar, comentarios como "No hagas esto nunca", no son la manera de hacerlo. Escribe tu código de manera que esas acciones no se puedan ejecutar nunca.

Parte 1: Introducción
Parte 2: Automatizar y control de versiones
Parte 3: Directorios
Parte 4: Claves
Parte 5: Simplificación y documentación