Resúmenes públicos de tl;dr con la etiqueta «buenas practicas».
La documentación es crucial porque 'el código se lee más de lo que se escribe' (Guido van Rossum) y sin buena documentación la gente no usará el software (Daniele Procida). Comentarios: para desarrolladores, explican el 'porqué' del código. Deben ser breves (máx. 72 caracteres) y seguir reglas como estar cerca del código que describen.
Un buen documento de diseño puede ahorrar años de tiempo de desarrollo. Obliga a pensar decisiones importantes antes de perder tiempo en la implementación incorrecta. Se debe escribir un documento de diseño cuando el proyecto es complejo o arriesgado, involucra a múltiples personas, dura más de tres meses, implica colaboración entre equipos o tiene requisitos ambiguos.