La vida es demasiado corta para escribir basura que nadie va a leer; si escribes basura, nadie la leerá. Por lo tanto, un poco de buena documentación es lo mejor. Los gerentes a menudo no entienden esto, porque incluso una mala documentación les da una falsa sensación de seguridad de que no dependen de sus programadores. Si alguien insiste absolutamente en que escribas documentación verdaderamente inútil, di 'sí' y comienza discretamente a buscar un trabajo mejor.
No hay nada tan efectivo como incluir una estimación precisa del tiempo que tomará producir buena documentación en una estimación para reducir la demanda de documentación. La verdad es fría y dura: la documentación, al igual que las pruebas, puede llevar muchas veces más tiempo que desarrollar código.
Escribir buena documentación es, ante todo, escribir bien. Te sugiero que encuentres libros sobre escritura, los estudies y practiques. Pero incluso si eres un mal escritor o tienes poco dominio del idioma en el que debes documentar, la Regla de Oro es todo lo que realmente necesitas: 'Haz a los demás lo que te gustaría que te hicieran a ti'. Tómate el tiempo para pensar realmente en quién leerá tu documentación, lo que necesitan obtener de ella y cómo puedes enseñárselo. Si haces eso, serás un escritor de documentación por encima del promedio y un buen programador.
Cuando se trata de documentar el código en sí, en lugar de producir documentos que realmente puedan ser leídos por no programadores, los mejores programadores que he conocido comparten un sentimiento universal: escribe código autoexplicativo y documenta el código solo en los lugares en los que no puedes hacerlo claro escribiendo el código mismo. Hay dos buenas razones para esto. En primer lugar, cualquier persona que necesite ver documentación a nivel de código, en la mayoría de los casos, podrá y preferirá leer el código de todos modos. Es cierto que esto parece más fácil para el programador experimentado que para el principiante. Más importante aún, sin embargo, es que el código y la documentación no pueden ser inconsistentes si no hay documentación. El código fuente puede ser, en el peor de los casos, incorrecto y confuso. La documentación, si no está escrita perfectamente, puede mentir, y eso es mil veces peor.
Esto no facilita las cosas al programador responsable. ¿Cómo se escribe código autoexplicativo? ¿Qué significa eso siquiera? Significa:
- Escribir código sabiendo que alguien tendrá que leerlo.
- Aplicar la regla de oro.
- Elegir una solución que sea directa, incluso si podrías usar otra solución más rápida.
- Sacrificar pequeñas optimizaciones que oscurecen el código.
- Pensar en el lector y dedicar parte de tu tiempo precioso para facilitarle la comprensión.
- Nunca usar un nombre de función como foo, bar o doIt.
Siguiente ¿Cómo trabajar con un código deficiente?