¿Cómo hacer documentación para el código y por qué el software (a menudo) está mal documentado?

¿Cómo documentar el código?

Ya tienes una pista: mira cómo se documenta la API de Java.

De manera más general, no existe un conjunto único de reglas que se apliquen a cada proyecto. Cuando trabajo en proyectos de gran escala críticos para el negocio, la documentación no tiene nada que ver con la que escribiría para una pequeña biblioteca de código abierto, que, a su vez, no tiene nada que ver con la documentación de mi proyecto personal de mediana escala. .

¿Por qué muchos proyectos de código abierto no están bien documentados?

Porque la mayoría de los proyectos de código abierto los hacen personas que contribuyen a esos proyectos porque es divertido. La mayoría de los programadores y desarrolladores consideran que escribir documentación no es lo suficientemente divertido para hacerlo gratis.

Por qué muchos proyectos de código cerrado no están bien documentados?

Porque cuesta una gran cantidad de dinero (1) escribir buena documentación y (2) mantenerla.

1. El El costo (costo de redactar la documentación) es claramente visible para las partes interesadas: si su equipo solicita pasar los próximos dos meses documentando el proyecto, son dos meses adicionales de salario para pagar.

2. El lo El costo de plazo (costo de mantenimiento de la documentación) se vuelve bastante fácil para los gerentes y, a menudo, es el primer objetivo cuando deben reducir el costo o acortar las demoras. Esto causa un problema adicional de documentación obsoleta que rápidamente se vuelve inútil y es extremadamente costosa de actualizar.

3. Los ahorros a largo plazo (ahorros por no tener que perder unos días explorando el El código heredado solo para comprender algo básico que debería haberse documentado hace años) son, por otro lado, difíciles de medir, lo que confirma la sensación de algunos gerentes de que escribir y mantener documentación es una pérdida de tiempo.

Lo que observo a menudo es que:

1. Al principio, el equipo está dispuesto a documentar mucho.

2. Con el tiempo, la presión de los plazos y la falta de interés hacen que sea cada vez más difícil mantener la documentación.

3. Unos meses más tarde, una nueva persona que se une al proyecto prácticamente no puede usar la documentación, porque no se corresponde en absoluto con el sistema real.

4. Al darse cuenta de eso, la administración culpa a los desarrolladores por no mantener la documentación; los desarrolladores solicitan dedicar algunas semanas a actualizarlo.

   • Si la administración concede algunas semanas para eso, el ciclo se repite.

   • Si la gerencia se niega, basándose en la experiencia previa, solo aumenta la mala experiencia, ya que el producto carece de documentación, pero se pasaron algunos meses escribiéndolo y manteniéndolo.

La documentación debe ser un proceso continuo, al igual que las pruebas. Pasar una semana simplemente codificando algunos miles de LOC y volver a las pruebas y la documentación es muy, muy doloroso.

Cómo animar al equipo a escribir documentación?

De manera similar a las formas de alentar a las personas a escribir código limpio, a hacer refactorizaciones regulares, a usar patrones de diseño o a agregar suficientes pruebas unitarias.

• Predicar con el ejemplo. Si escribe buena documentación, sus pares podrían comenzar a hacerlo también.

• Realice revisiones sistemáticas de código, incluidas revisiones formales de código destinadas a inspeccionar la documentación.

• Si algunos miembros del equipo son particularmente antipáticos por la buena documentación (o la documentación en absoluto), discuta el tema con ellos en privado, para comprender cuáles son los impedimentos que les impiden escribir una mejor documentación. Si culpan a la falta de tiempo, verá la fuente de los problemas.

• Haga que la presencia o la falta de documentación sea mensurable durante unas semanas o meses, pero no céntrese en eso. Por ejemplo, puede medir la cantidad de líneas de comentarios por LOC, pero no lo convierta en una medida permanente, de lo contrario, los desarrolladores comenzarán a escribir comentarios largos pero sin sentido solo para deshacerse de las puntuaciones bajas.

• Utilice la gamificación. Esto viene junto con el punto anterior.

• Utilice refuerzo positivo / negativo.

• (Ver el comentario de SJuan76 ) Trate la falta de comentarios como errores. Por ejemplo, en Visual Studio, puede marcar una opción para generar documentación XML. Si también verifica que todas las advertencias se tratan como errores, la falta de un comentario en la parte superior de una clase o un método detendrá la compilación.

  En cuanto a los tres puntos anteriores, este debería usarse con cuidado. Lo usé por un tiempo con un equipo particularmente duro de programadores principiantes, y terminó con comentarios que cumplen con StyleCop como ese:

  /// <summary> /// Gets or sets the PrimaryHandling. /// </summary> public Workflow PrimaryHandling { get; set; }  

que, hm …, no fueron particularmente útiles.

Recuerda: nada automatizado puede ayudarte a identificar comentarios negativos cuando los programadores quieran joder contigo . Solo código las revisiones y otras tareas humanas ayudarán.

¿Hay buenos ejemplos de cuando se necesita documentación mínima o nula?

No se necesita documentación que explique la arquitectura y el diseño :

• Para un prototipo,

• Para un proyecto personal escrito en unas pocas horas para lograr una tarea, estando bastante seguro de que este proyecto no se mantendrá por más tiempo,

• Para cualquier proyecto donde sea obvio, dada la Su pequeño tamaño, junto con el código particularmente limpio, le permitirá dedicar más tiempo a escribir documentación que todos los futuros mantenedores explorando el código.

La documentación en código (comentarios de código) no es necesaria según algunos desarrolladores cuando el código es autodocumentado. Para ellos, la presencia de comentarios no es, excepto en casos excepcionales, una buena señal, sino una señal de que el código no se refactorizó lo suficiente como para ser claro sin necesidad de comentarios.

Siento que deberíamos tener una revisión de la documentación después de que se entrega un proyecto.

Si su proyecto se entrega al menos una vez por semana, es el camino a seguir. Si su proyecto no es ágil y se entrega a intervalos de seis meses, haga revisiones más regulares.

Comentarios

• Para ‘ cómo animar ‘, agregaría que muchos IDE permiten la notificación de documentación faltante como advertencias. Alternativamente, tal vez se pueda hacer un análisis estático de la documentación en el OSB (por supuesto, eso solo no sería suficiente).
• @ SJuan76: Efectivamente. Visual Studio puede incluso tratar la falta de comentarios como un error en tiempo de compilación. Edité mi respuesta para agregar una nota sobre eso.
• @ArseniMourzenko – Leí que podríamos fomentar cierta documentación en Agile agregando historias para la documentación. Pero, estos no deben bloquear las otras historias, es decir, la definición de otras historias de hecho, no debe incluir la finalización de las historias de documentación. ¿Cómo suena eso?
• @ArseniMourzenko – Yo ‘ quisiera agregar dos puntos más a su respuesta. (1) En Jira, etc., agregue una tarea para la documentación todo el tiempo. (2) Haga que 2 personas más revisen los documentos & póngalo como una tarea también. De esa manera, se recordará a las personas que deben documentar & para evitar escribir documentos de baja calidad (debido a la revisión). Si no ‘ no le da prioridad & revísela, entonces se volverá malo. Sé que Amazon hace muchas & revisiones de documentos, quizás demasiado.

Creo que debería hacer una distinción entre comentarios y documentación. Si bien los comentarios son descriptivos, carecen de coherencia, están dispersos por todo el código. Los comentarios nunca deberían compensar el código que no es suficientemente autodescriptivo, sino que deberían indicar a otros programadores las partes complicadas.

Si el código debería documentarse depende de la escala del proyecto. Seguramente hay gente que cree que todo debería estar documentado, y parece fácil justificar ese pensamiento porque quién se atrevería a oponerse documentar el conocimiento? Afortunadamente, el desarrollo de software no es ciencia, y el mundo no colapsa si los detalles detrás de su pequeño programa se vuelven oscuros. Ahora, con respecto a un software profesional para uso de muchos desarrolladores, sí, obviamente, debería documentar su código. Pero si está en la posición codificar en ese nivel, entonces obviamente lo sabrías.

tl; dr

Si estás pidiendo que todos los proyectos estén bien documentados, estás pidiendo demasiado .

Comentarios

• Fortunately software development is not science Por favor, cuénteme más sobre por qué cree esto.
• @Borat – El desarrollo de software es una disciplina de ingeniería, lo que implica que utiliza las herramientas proporcionadas por la ciencia.
• No estoy pidiendo que todo esté documentado. Debería ser lo suficiente para ofrecer una descripción general de alto nivel de lo que hace un sistema y un código. Por ejemplo, dígame cómo usar mi televisor. No ‘ me importa si usa LCD, CRT, Tubos de vacío o dispositivos de estado sólido para hacer el trabajo . Si un reparador quiere esa información, entonces cree documentación separada para él.
• Si desea una descripción general de alto nivel, los nombres de los identificadores son suficientes. Al igual que el botón de su televisor puede tener una etiqueta » On «. Así que estás pidiendo detalles de bajo nivel.
• @LeopoldAsperger: Creo que Borat está hablando de documentar la arquitectura y el diseño, no de métodos en clases.