it-swarm-es.com

¿Cuánta documentación es suficiente?

¿Cuánta documentación técnica (para futuros desarrolladores) es suficiente ? ¿Existe una proporción adecuada entre las horas de codificación y las horas de documentación?

Papadimoulis argumenta que deberías

producir la menor cantidad de documentación necesaria para facilitar la mayor comprensión,

¿Es una buena guía o hay cosas específicas que debería crear?

15
C. Ross

¿Qué tal algunas pruebas de usabilidad en pasillos? Muestre el código y la documentación a un desarrollador que no esté familiarizado con el proyecto. Cuando puede hacer eso sin una necesidad abrumadora de explicar algo mientras los ve revisar el código, tiene suficiente.

25
JohnFx

La perfection est atteinte non pas quand il n’y a plus rien à ajouter, mais quand il n’y a plus rien à retirer.
Antoine de Saint-Exupéry

12
Benoit

He estado pensando en este tema por un tiempo.

Mi conclusión es: no es una cuestión de cantidad, sino de calidad y contexto.

Por ejemplo, una estructura de proyecto adecuada supera a los comentarios que explican dónde se encuentran los archivos (implementación frente a intensión)

De manera similar, la clasificación para aclarar el contexto es mejor que nombrar (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 tener que existir).

El código en sí mismo no es lo suficientemente bueno 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 o el razonamiento del dominio no deberían hacerlo, pero si la lógica o el razonamiento del dominio cambia, el código definitivamente lo hará.

La coherencia también es muy importante: la convención por sí sola es inútil si no es coherente.

Los patrones de diseño no son solo 'buenas prácticas', es una jerga que nosotros los desarrolladores debemos entender. Decirle a un desarrollador que agregue un nuevo tipo a Factory se comprende mejor 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 contexto y al dominio. A veces, la duplicación de funciones 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, trabaja en la industria médica. En su método, escribe "IsPatientSecure = true;"

Ahora, cualquier programador decente puede darse cuenta de 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 conducen a este punto (y quizás lo que aún debe suceder).

Tal vez esta publicación parezca filosófica en el mejor de los casos, pero recuerde que es 'razonamiento' o 'lógica' sobre lo que está escribiendo, no código.

3
Shelakel

Suficiente para que deje de adivinarse.

Si en algún momento durante tu trabajo piensas "hmm, tal vez debería documentar esto", hazlo. Entonces, si ha escrito algo de documentación y dice "tal vez debería explicar esto más", continúe y hágalo.

Enjuague-repita hasta que esa sensación desaparezca.

1
Mark Canlas

Descubrí que un enfoque impulsado por el riesgo como el presentado en el libro de George Fairbanks Arquitectura de software suficiente funciona extremadamente bien para comprender cuánta documentación es suficiente. Puede leer la sección que presenta este concepto (capítulo 3) en su sitio web pero la idea principal es:

  • Exprese las cosas que le preocupan sobre la "comprensión del sistema" como riesgos.
  • Prioriza los riesgos
  • Mitigue los riesgos hasta que su equipo sienta que el riesgo del proyecto se ha reducido lo suficiente. En este caso, probablemente creará algún tipo de documentación.

Para ayudar a calibrar las inquietudes para que pueda priorizar los riesgos, me ha resultado útil identificar un par de objetivos conocidos como mbral de éxito , que es el conjunto mínimo de objetivos que su equipo considera que es un proyecto "exitoso" debe lograr. Desde la perspectiva de la documentación, un ejemplo de ToS podría ser algo así como "Un desarrollador debería poder crear un complemento simple dentro de las 4 horas posteriores a la adquisición del marco por primera vez".

Ahora identifique algunos riesgos. Con el sistema que ha construido (o está construyendo), ¿cuáles son las cosas que más preocupan a su equipo? Exprese esto como declaraciones de riesgo. Me gusta el estilo de consecuencia de la condición del SEI, pero hay otros. Ejemplos:

  • El modelo de datos es amplio y complejo; Es posible que los desarrolladores no sepan qué elementos de datos utilizar en una situación determinada.
  • El sistema tiene límites de conexión API para aumentar la confiabilidad; los desarrolladores pueden sobrepasar accidentalmente el límite de conexión.
  • Los complementos se consumen en varios pasos secuenciales; Es posible que los desarrolladores no creen complementos con estos pasos ordenados en mente.

Ahora, como equipo, priorice los riesgos. La votación múltiple funciona muy bien.

Mitigue los riesgos de máxima prioridad y repita el comienzo con la identificación hasta que el riesgo de que su proyecto falle (definido por el Umbral de éxito) esté dentro de un límite tolerable. Por lo general, esto significará que tendrá algunos riesgos que, según el equipo, no son una gran preocupación. Tenga en cuenta que probablemente no querrá mitigar todos los riesgos. Un ejemplo de estrategia de mitigación para el último riesgo anterior podría ser crear un tutorial.

1
Michael

Estoy de acuerdo con la cita de Papadimouslis. El código fuente puede hablar por sí mismo, pero el código no puede decirle por qué existe, cómo debe usarse y cómo debe comportarse el código.

No conozco una buena proporción.

Heredé cientos de líneas de código con muy poca documentación. Me resultó difícil entender por qué se escribió el código. Después de descubrir por qué se escribió el código, tuve que averiguar cómo usar el código. Después de descubrir eso, tuve que entender cómo se supone que debe comportarse para poder soportar y mantener el código.

Solo por experiencia, no haga comentarios demasiado específicos o terminará teniendo que mantener el código real Y la documentación. Es una pesadilla cuando la documentación y el código no están sincronizados.

1
Kin

Lo menos posible, pero tanto como sea necesario

No recuerdo dónde y cuándo lo escuché por primera vez, pero es una máxima con muchas aplicaciones.

Cuanto más compleja sea la tecnología o la aplicación, más documentación se necesitaría (obviamente), pero claramente no querrá perder el tiempo exagerando.

La 'prueba de pasillo' de JohnFx es sólida. Pero confía en ti mismo; usted desarrolló el código, por lo que usted, entre todas las personas, debe tener una idea de los elementos que necesitan atención adicional y los elementos que serán obvios para todos. Piense en las dificultades que tuvo al desarrollar el código y probablemente tendrá una idea de lo que verá otro desarrollador cuando mire su código.

Olvídese de cualquier relación entre el esfuerzo dedicado a codificar y el esfuerzo dedicado a documentar.

1
cjmUK

Creo que no se puede poner esto en reglas exactas. El motivo de la documentación es proporcionar el conocimiento que no se obtiene fácilmente del código en bruto en una forma para que otros puedan entender y quizás incluso mantener dicho código en bruto.

Por lo tanto, la única forma de saber si ha documentado lo suficiente es preguntar a la audiencia objetivo si es lo suficientemente bueno. Creo que el proceso de "revisión por pares" es muy bueno para hacer esto desde el principio. Observe cuántas explicaciones se necesitan para que su compañero entienda de lo que está hablando y trabaje para minimizarlo.

Si nunca ha hecho esto antes, no puede estimar cuánto trabajo tomará, pero después de algunas iteraciones obtendrá una idea mucho mejor de cuánto se necesita.

0
user1249