¿Cuánta documentación técnica (para futuros desarrolladores) es suficiente ? ¿Existe una relación entre las horas de codificación y las horas de documentación que sea apropiada?
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 estar creando?
documentation
Cruzar
fuente
fuente
Respuestas:
¿Qué tal algunas pruebas de usabilidad en el pasillo? Muestre el código y la documentación a un desarrollador que no esté familiarizado con el proyecto. Cuando puede hacerlo sin un impulso abrumador de explicar algo mientras los ve revisar el código, tiene suficiente.
fuente
La perfection est atteinte non pas quand il n'y a plus rien à ajouter, mais quand il n'y a plus rien à jubile.
(en inglés: la perfección no se alcanza cuando no hay nada más que agregar, pero cuando no hay nada más que eliminar).Antoine de Saint-Exupéry
fuente
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.
fuente
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 sé una buena proporción.
Heredé cientos de líneas de código con muy poca documentación. Se me hizo difícil entender por qué se escribió el código. Después de descubrir por qué se escribió el código, tuve que descubrir cómo usarlo. Después de descubrirlo, 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.
fuente
Suficiente para que dejes de cuestionarte a ti mismo.
Si en algún momento durante su trabajo es como "hmm, tal vez debería documentar esto", continúe y hágalo. Luego, si ha escrito alguna documentación y dice "tal vez debería explicar esto más", continúe y haga eso.
Enjuague y repita hasta que esa sensación desaparezca.
fuente
Descubrí que un enfoque basado en el riesgo, como el presentado en el libro de George Fairbanks, Just Enough Software Architecture, 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:
Para ayudar a calibrar las inquietudes para que pueda priorizar los riesgos, he encontrado útil identificar un par de objetivos conocidos como el Umbral de éxito , ese es el conjunto mínimo de objetivos que su equipo cree que debe alcanzar un proyecto "exitoso". Desde el punto de vista de la documentación, un ejemplo de ToS podría ser algo así como "Un desarrollador debería ser capaz de construir un complemento simple dentro de las 4 horas de haber elegido el marco por primera vez".
Ahora identifica algunos riesgos. Con el sistema que ha construido (o está construyendo), ¿cuáles son las cosas que más preocupan a su equipo? Frase estos como declaraciones de riesgo. Me gusta el estilo de condición-consecuencia del SEI pero hay otros. Ejemplos:
Ahora como equipo, priorice los riesgos. La votación múltiple funciona extremadamente bien.
Mitigue los riesgos de máxima prioridad y repita comenzando 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. En general, esto significará que tendrá algunos riesgos que el equipo acuerda que 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.
fuente
No recuerdo dónde y cuándo escuché eso por primera vez, pero es una máxima con muchas aplicaciones.
Cuanto más compleja sea la tecnología o la aplicación, se necesitará más documentación (obviamente), pero claramente no querrá perder el tiempo yendo por la borda.
La 'prueba del pasillo' de JohnFx es sólida. Pero confía en ti mismo; usted desarrolló el código y, por lo tanto, de todas las personas debería 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 es probable que tenga una idea de lo que verá otro desarrollador cuando vea su código.
Olvide cualquier relación entre el esfuerzo dedicado a codificar y el esfuerzo dedicado a documentar.
fuente
Creo que no puedes poner esto en reglas exactas. La razón para documentar es proporcionar el conocimiento que no se puede obtener fácilmente del código sin formato en una forma para que otros puedan entender y tal vez incluso mantener dicho código sin formato.
Por lo tanto, la única forma de saber si ha documentado lo suficiente es preguntarle al público objetivo si es lo suficientemente bueno. Creo que el proceso de "revisión por pares" es muy bueno para hacer esto por adelantado. Observe la cantidad de explicaciones necesarias para que su compañero entienda de qué 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.
fuente