Como has visto hasta ahora, documentar código correctamente tampoco es complicado, es una cuestión de voluntad y costumbre de hacerlo. En resumen, las reglas básicas para tener código bien documentado son:
- No comentes código evidente o trivial.
- Explica cualquier cosa que no sea evidente viendo solo el código.
- Usa siempre nombres de variables auto-explicativos, aunque sean variables auxiliares de un solo uso. Ayudan a la comprensión.
- Usa nombres de funciones correctos: que expliquen su cometido, pero que no sean un párrafo. Simples y concisos.
- Describe las variables menos evidentes, para darles contexto.
- Explica todo lo que sea necesario, aunque ocupe varias líneas de comentarios. Explicar la lógica de negocio inherente al código ayuda a su gestión.
- Explica conceptos complejos que otro programador podría no conocer o recordar. Te ayudará a ti en el futuro y a otros si cogen tu código.
- Explica soluciones que se probaron pero que finalmente no sirvieron. Así evitarás que otros comentan el mismo error que ya cometiste tú.
Siguiendo estas sencillas normas básicas, conseguirás lo siguiente:
- Podrás recordar cómo funcionaba tu código mucho tiempo después de haberlo creado.
- Otro podrá saber qué hace tu código y por qué, sin tener que descifrarlo.
- Podrás saber qué hace un bloque de código complejo sin tener que analizar ni una línea, simplemente leyéndolo en los comentarios.
- Podrás averiguar por qué no se usó una característica concreta que hoy usarías (¿quizá tenía un bug en su momento?).
- Podrás descartar otras soluciones que ya se probaron antes pero que daban problemas (quizá parecían evidentes al principio pero tenían algún inconveniente).
Recuerda también que la documentación fuera del código… ¡suele estar obsoleta! La teoría es muy bonita, pero nunca he visto documentación actualizada. Eso no quiere decir que un proyecto no se deba documentar: los requisitos deben estar ahí, los tests deben estar ahí, pero el código es lo que manda al final, así que…
¡Difunde el movimiento CodeDoc! ¡Por un código más sano!
¿Añadirías algo más?
Si crees que algo de lo que he expuesto tiene algún error o problema, o crees que se podría añadir algo más, puedes contactar conmigo en cualquiera de los canales que se muestran a la derecha (o abajo, si estás usando el móvil). Estaré encantado de debatir sobre estos asuntos para mejorar el movimiento.
Cualquier aportación relevante que hagas se mostrará como tuya.