¿Deberías documentar todo o solo la mayoría?

Parece un poco controvertido el tema de documentar todo, incluida la sintaxis "JavaBean" de captadores y establecedores para campos: la gente dice que es innecesariamente largo y repetitivo romper SECO (no repetir) , que la convención de nomenclatura debería explicar todo , y satura el código / documentación. A veces esos argumentos funcionan. Pero otras veces, terminas con esto:

Lo anterior es común a los proyectos de código abierto que siguen audazmente esos principios. Te queda documentación completamente inútil . Eso no explica nada sobre lo que está sucediendo debajo, los posibles efectos o incluso cuál es el valor esperado (¿podría ser nulo o nunca nulo? No lo sé; el Javadoc no me lo dice).

Entonces, ¿cuándo debo documentar? ¿Documento todo incluso si ocasionalmente satura el código? ¿O no documento nada ya que a mis ojos es "obvio"?

Documente todo lo que tenga sentido documentar .

En un mundo ideal, sí, documentarías todo. Sin embargo, en la Tierra, tenemos plazos, recortes de funciones, familias y amigos para visitar, vacaciones para tomar, solo 24 horas en un día y solo 365 días en un año. Simplemente no hay tiempo suficiente para documentar todo. Entonces, de manera óptima, documente todo lo que pueda (no podrá hacer), pero obtenga el máximo provecho de su dinero al:

• Haga que el código legible y las firmas de métodos sean lo más obvias posible para que sea menos probable que se necesite documentar.
• Documentar primero las cosas más oscuras. Ayude a otros documentando los trucos locos que tuvo que hacer para sacar las cosas por la puerta.
• Documente el por qué antes del qué : no comente qué hace algo, como "Iterar sobre los registros de clientes donde el saldo es menor que cero y la calificación es menor que uno y agregarlos a la lista de Clientes exentos". Documente por qué los está agregando a la lista en inglés simple (o en el idioma de su equipo), como "Dado que estos clientes tienen un saldo negativo y calificaciones bajas, nos están haciendo perder dinero, por lo que debe excluirlos de poder pagar.

Siga documentando hasta que pueda ver a alguien más leerlo sin sentir la necesidad de explicar nada.

La semana pasada hubo un gran artículo sobre documentación en The Daily WTF. Creo que lo dice todo, así que solo dejaré el enlace:

http://thedailywtf.com/Articles/Documentation-Done-Right.aspx

Básicamente dice que no debes documentar algo si no va a ser útil (parte de la documentación se deja pudrir en un cajón) y documenta la menor cantidad de información que se necesita para comprender una determinada parte del proyecto. Demasiada documentación simplemente confunde al lector.

Realmente depende de qué tan legible sea el código para la audiencia que lo lea. Averigua quién es la audiencia para leer tu código y haz que alguien que cumpla con ese perfil lea tu código.

Otro enfoque sería revisar su propio código después de una semana y ver si aún comprende lo que hizo, si no lo hace, documentarlo y revisar el código en aproximadamente dos semanas.

Si bien agradezco una documentación clara y extensa, no hay nada como el código autodocumentado. Entonces, la conclusión (para mí) es:

Sospeche mucho de la documentación (código fuente); intente hacerlo redundante mejorando el código, pero no evite documentar clara y completamente cuando sea necesario.

Por supuesto, bajo ciertas circunstancias, la documentación puede ser requerida por otras razones que no sean "explicar lo que está haciendo el código" (por ejemplo: gran equipo base, estándares de la organización, etc.).

Mi sugerencia sobre la documentación es que si hay algo elegante en el código, eso pertenece a un documento que debe mantenerse actualizado. La fantasía está sujeta a mucha interpretación, en mi opinión es cuando algo se hace de una manera particular que puede tener efectos secundarios que deben tenerse en cuenta, por ejemplo, algo que se puede hacer de forma recursiva para garantizar que los elementos de nietos se procesen al pasar por un árbol de nodos realizar alguna prueba en todos los descendientes. Articular por qué se hizo algo de una manera particular puede ser una buena manera de saber si hubo o no una buena razón para usar algo.

En términos simples, la documentación está ahí para ayudar a los desarrolladores ahora y a los encargados del mantenimiento en el futuro.

Si recuerda esa máxima simple, entonces el nivel de documentación debe ser autodefinido.

La documentación, por el bien de la documentación, es una pérdida de tiempo ... pero explicar hoy lo que está haciendo es más útil que alguien que tenga que aplicar ingeniería inversa a su código dentro de cinco años.

Personalmente voy con el enfoque de considerar documentar todo. Es decir, al codificar, considero en cada punto si la documentación agregaría valor. La mayoría de las veces la respuesta es sí para exactamente los tipos de restricciones y conocimiento de dominio mencionados en la pregunta original. Por ejemplo, capacidad nula, restricciones únicas, interpretación del campo en el dominio más amplio.

Para evitar la duplicación, tiendo a documentar en gran medida las principales clases de API con este tipo de información. Luego, solo documente implementaciones y componentes internos donde haya un comportamiento no obvio o inconsistente. Creo que esto funciona bien, ya que son los usuarios de la API los que necesitan más ayuda y documentación, por lo general es seguro asumir que las personas que modifican la implementación conocen la API, así que tengan este conocimiento.

También tiendo a documentar solo a los captadores. No duplico documentación en setters, definiciones de campo y parámetros de constructor. Solo documento comportamientos no obvios, como los valores predeterminados en estos lugares. Cualquier comportamiento que pueda inferirse de la documentación del captador no está documentado. Por ejemplo, si el getter está documentado como nulo sin retorno, generalmente no documento que no se puede pasar nulo al setter, a menos que haya un valor predeterminado.

A algunas personas les gusta marcar este acto de "considerar la documentación" agregando comentarios vacíos donde han considerado la documentación pero la encontraron innecesaria. No me gusta esta práctica, ya que solo llena el código y se interpone en el camino.