He estado pensando en este tema por un tiempo.
Mi conclusión es que no se trata de cantidad, sino de calidad y contexto.
Por ejemplo, una estructura de proyecto adecuada supera los comentarios que explican dónde se encuentran los archivos (implementación frente a intención)
Del mismo modo, la clasificación para aclarar el contexto supera la denominación (Id en un paciente -> Id. Del paciente).
Creo que DDD tiene algo que decir en la buena documentación: la clasificación proporciona contexto, el contexto crea límites y los límites conducen a implementaciones intencionales (aquí es donde pertenece, en lugar de que deba existir).
El código en sí mismo no es lo suficientemente bueno como para ser considerado documentación. El problema en la mayoría de los casos no reside en el hecho de que el funcionamiento de los códigos está comentado o no, sino que la fuerza impulsora (lógica de dominio) no lo está.
A veces olvidamos quién es el jefe: si el código cambia, la lógica del dominio o el razonamiento no deberían, pero si la lógica del dominio o el razonamiento cambian, el código definitivamente lo hará.
La consistencia también es muy importante: la convención en sí misma es inútil si no es consistente.
Los patrones de diseño no son solo una 'buena práctica': es una jerga que los desarrolladores debemos entender. Se entiende mejor decirle a un desarrollador que agregue un nuevo tipo a una Fábrica que agregar un nuevo tipo a un método (donde el contexto y la consistencia son débiles o faltan).
La mitad de la lucha es familiaridad .
En una nota al margen, las API que parecen favorecer una gran cantidad de documentación también son muy sensibles al dominio y al contexto. A veces, la funcionalidad de duplicación no es mala (lo mismo, contextos diferentes) y debe tratarse como algo separado.
En términos de comentarios, siempre es bueno señalar la lógica del dominio detrás del razonamiento.
Por ejemplo, está trabajando en la industria médica. En su método, escribe "IsPatientSecure = true;"
Ahora, cualquier programador decente puede descubrir que el paciente está siendo marcado como seguro. ¿Pero por qué? ¿Cuáles son las implicaciones?
En este caso, el paciente es un recluso que fue trasladado de forma segura a un hospital fuera de las instalaciones. Sabiendo esto, es más fácil imaginar los eventos que condujeron a este punto (y tal vez lo que todavía tiene que suceder).
Tal vez esta publicación parece filosófica en el mejor de los casos, pero recuerde que está escribiendo "razonamiento" o "lógica", no código.