E12: Comentarios en el código y documentación

Ni cero, ni uno

Retomamos uno de los asuntos mencionados en el episodio 10, los comentarios en el código y de paso hablamos de otros tipos de documentación. Entre el extremo de escribir comentarios para absolutamente todo y el de escribir cero comentarios, está el punto en el que ponemos foco en el episodio.

Ejemplos de comentarios útiles:

• Explicar por qué, para qué y también por qué no, y qué evitar.
• Por qué se decidió implementar concretamente de la manera que está.
• Por qué se descartó implementarlo de otra manera que quizás parece más obvia o natural.
• Para qué se usa ese código, dónde encaja, qué otros posibles usos podría tener. Si existe alguna situación en la que pudiera ser prescindible y borrarse.
• Lo que se probó y no funcionó, para que no vuelva a invertir el tiempo la persona que viene.
• Lo que se estudió y se descartó. Cuáles fueron las conclusiones de la investigación.
• Código legado que no se entiende pero que se consigue entender después de mucho trabajo, entonces ponle un comentario, si no lo puedes tocar al menos que quede algo documentado.
• Los efectos colaterales que provocarían cambios aparentemente inocuos. Por ejemplo condiciones de carrera o interbloqueos al cambiar de orden dos líneas de código. Un salto de línea que parece insignificante y hace que luego la importación de un fichero en un sistema externo deje de funcionar...
• Si existen parámetros globales de configuración u otros factores externos que podrían afectar a este código o que haya que tener en cuenta para su correcto funcionamiento.
• Si en caso de fallo se puede ir a mirar algún tipo de log o cualquier otra forma de depuración. Sobre todo en tests de integración.
• Si el sistema puede crecer hasta un punto en que el código dejará de servir. Es decir, si hemos elegido una solución potencialmente de corto recorrido. Por ejemplo una librería que ya no tiene soporte o un sistema que sólo aguantará hasta N usuarios.
• Ayudar a entender cómo se comporta una librería o framework cuando interactuamos de cierta forma que podría no estar documentada o ser poco intuitiva.
• Describir un API pública de propósito general.
• Comentarios en el PR con las herramientas de Github.
• Poner en un comentario la url a la documentacion de api, una URL.
• Los comentarios como punto intermedio de refactoring, mientras vas entendiendo cosas del codigo legacy y no te atreves a tocar, como andamiaje cognitivo.
• Comportamientos extraños o poco intiuitivos de software de terceros.
• Comentar por que esta el framework configurado de cierta forma, que error se generaba sino se configura asi. La convencion sobre configuracion a veces requiere de un comentario.

En cuanto a tipos de documentación que me resulta útil:

• API - swagger/open api
• Bitácora de proyecto / changelog.
• Los commits en el control de versiones, Git.
• Docs de api (JavaDoc...)
• Post Morten analysis.
• Instrucciones de instalacion y despliegue en entornos
• Targs mejor que arboles de categorias.
• Diagramas de componentes de alto nivel, arquitectura del sistema.
• Bugtracker o gestor de incidencias como medida de progreso y mejora.
• Manuales de usuario.

Muchísimas gracias a todas las personas que han colaborado en este episodio:

• Miriam Carrascal
• Juan Antonio Quintana
• Adrián Ferrera
• Ulises Santana
• Luis Rodriguez
• Mireia Scholz
• Raúl Padilla

Newsletters:

• Carlos Blé
• Lean Mind