Capítulo 6- Simplificación
- Simplifica para eliminar redundancias
- Simplifica para mejorar la claridad
- En caso contrario, no simplifiques.
Capítulo 7- Documentación
- No escribas documentación que no mantendrás
- El código debería autodocumentarse
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
No hay comentarios:
Publicar un comentario