¿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.
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.
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.
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:
Al principio, el equipo está dispuesto a documentar mucho.
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.
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.
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.