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

Hay algunos buenos ejemplos de código bien documentado, como java api. Pero, una gran cantidad de código en proyectos públicos, como git y proyectos internos de empresas, está mal documentado y no es muy amigable para los recién llegados.

En todos mis períodos de desarrollo de software, he tenido que lidiar con código mal documentado. Noté las siguientes cosas:

1. Poco o nada de comentarios en el código.
2. Los nombres de métodos y variables no se describen por sí mismos.
3. Hay poca o ninguna documentación sobre cómo encaja el código en el sistema o los procesos comerciales.
4. Contratar desarrolladores malos o no asesorar a los buenos. No pueden escribir código simple y limpio. Por lo tanto, es difícil o imposible para cualquiera, incluido el desarrollador, documentar el código.

Como resultado, tuve que pasar por un montón de código y hablar con muchas personas para aprender cosas. Siento que esto desperdicia el tiempo de todos. También crea la necesidad de sesiones de transferencia de conocimiento / KT para los recién llegados a un proyecto.

Aprendí que la documentación no recibe la atención que merece debido a las siguientes razones:

1. Pereza.
2. A los desarrolladores no les gusta hacer nada más que código.
3. Seguridad en el empleo. (Si nadie puede entender su código fácilmente, entonces es posible que no sea fácilmente reemplazable).
4. Los plazos difíciles dejan poco tiempo para documentar.

Por lo tanto, me pregunto si hay una manera de alentar y aplicar buenas prácticas de documentación en una empresa o proyecto. ¿Cuáles son las estrategias que se utilizarán para crear documentación decente para los sistemas y el código de cualquier proyecto, independientemente de su complejidad? ¿Hay buenos ejemplos de cuándo se necesita una documentación mínima o nula?

En mi humilde opinión, creo que deberíamos tener una revisión de la documentación después de la entrega de un proyecto. Si no es simple, conciso, ilustrativo y fácil de usar, el desarrollador o el ingeniero de documentación técnica son responsables de ello y se encargan de arreglarlo. Tampoco espero que la gente haga montones de documentación, no espero que sea fácil de usar como los libros principales, pero espero que elimine la necesidad de horas de análisis y sesiones de KT derrochadoras.

¿Hay alguna manera de terminar o aliviar esta locura? ¿"Desarrollo impulsado por documentos" quizás?

¿Cómo documentar el código?

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

En términos más generales, no existe un conjunto único de reglas que se apliquen a cada proyecto. Cuando trabajo en proyectos a 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 están hechos por 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 como para hacerlo de forma gratuita.

¿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 costo inmediato (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, pagarán dos meses adicionales de salario.

2. El costo a largo plazo (costo de mantenimiento de la documentación) también se hace bastante fácil de percibir para los gerentes, y a menudo es el primer objetivo cuando deben reducir el costo o acortar los retrasos. Esto causa un problema adicional de documentación desactualizada 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 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 el sentimiento de algunos gerentes que escribir y mantener documentación es una pérdida de tiempo.

Lo que a menudo observo 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 dificultan cada vez más el mantenimiento de 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, ya que no corresponde en absoluto al sistema real.

4. Al darse cuenta de eso, la gerencia culpa a los desarrolladores por no mantener la documentación; los desarrolladores piden pasar unas semanas actualizándolo.

   • Si la gerencia concede algunas semanas para eso, el ciclo se repite.

   • Si la administración se niega, según la experiencia previa, solo aumenta la mala experiencia, ya que el producto carece de documentación, pero pasaron unos meses escribiendo y manteniendo.

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

¿Cómo alentar al equipo a escribir documentación?

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

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

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

• Si algunos miembros del equipo son particularmente antipáticos a 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 medible durante algunas semanas o meses, pero no se concentre en eso. Por ejemplo, puede medir el número 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 los puntajes bajos.

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

• Use refuerzo positivo / negativo .

• (Vea 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 debe usarse con precaución. 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 fueron, hm ..., no particularmente útiles.

Recuerde: nada automatizado puede ayudarlo a identificar malos comentarios cuando los programadores quieren fastidiarlo . Solo las revisiones de código y otras tareas humanas ayudarán.

¿Hay buenos ejemplos de cuándo se necesita una 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 llevar a cabo una tarea, y al mismo tiempo estar bastante seguro de que este proyecto ya no se mantendrá,

• Para cualquier proyecto donde sea obvio, dado su pequeño tamaño, junto con el código particularmente limpio, pasará más tiempo escribiendo documentación que todos los futuros mantenedores explorando el código.

La documentación en el código (comentarios de código) no es necesaria según algunos desarrolladores cuando el código se auto documenta. Para ellos, la presencia de comentarios es, excepto en los casos raros, una buena señal, pero una señal de que el código no fue refactorizado lo suficiente como para ser claro sin la necesidad de comentarios.

Creo que deberíamos tener una revisión de la documentación después de que se entregue 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, realice revisiones más periódicas.

Creo que debería hacer una distinción entre comentarios y documentación. Si bien los comentarios son descriptivos, carecen de consistencia, están dispersos por todo el código. Los comentarios nunca deberían compensar el código que no se describe a sí mismo lo suficiente, sino que debería indicar a otros programadores sobre partes difíciles.

Si el código debe documentarse depende de la escala del proyecto. Seguramente hay personas que creen que todo debe documentarse, y parece fácil justificar ese pensamiento porque ¿quién se atrevería a oponerse a documentar el conocimiento? Afortunadamente, el desarrollo de software no es ciencia, y el mundo no se derrumba 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, debe documentar su código. Pero si está en condiciones de codificar en ese nivel, entonces obviamente lo sabría.

tl; dr

Si está pidiendo que cada proyecto esté bien documentado, entonces está pidiendo demasiado.