¿Qué debo incluir en el encabezado de la documentación de mi clase?

Estoy buscando un formato de documentación de clase informativo para mis clases de Entidad, Lógica empresarial y Acceso a datos.

Encontré los siguientes dos formatos desde aquí

Formato 1

///-----------------------------------------------------------------
///   Namespace:      <Class Namespace>
///   Class:          <Class Name>
///   Description:    <Description>
///   Author:         <Author>                    Date: <DateTime>
///   Notes:          <Notes>
///   Revision History:
///   Name:           Date:        Description:
///-----------------------------------------------------------------

Formato 2

// ===============================
// AUTHOR     :
// CREATE DATE     :
// PURPOSE     :
// SPECIAL NOTES:
// ===============================
// Change History:
//
//==================================

Siento que los siguientes son los elementos básicos

• Autor
• Fecha de creación
• Descripción
• Revisión histórica

como el espacio de nombres y el nombre de la clase estarán allí de todos modos.

Por favor, hágame saber sus pensamientos, ¿qué formato se recomienda y si hay una forma estándar de escribir el historial de revisiones?

La mayor parte de la información que ha sugerido allí se encontrará en el repositorio de origen.

Lo único que realmente necesita es la sección de propósito, que dice para qué sirve la clase.

¿Sería tedioso buscar en el repositorio cada vez que desee conocer la otra información? Yo diría que no. ¿Con qué frecuencia te importa quién fue el autor original? ¿O cuándo se creó el archivo por primera vez? Los complementos (como Ankh SVN para Visual Studio) a menudo le permiten hacer clic derecho dentro de su archivo actual y ver el registro de repositorio para el archivo, por lo que no es una molestia ver realmente esta información.

Además, si almacena el historial de versiones en un comentario, este comentario debe mantenerse. Entonces, con el tiempo existe la posibilidad de que te esté mintiendo. El repositorio de código fuente guarda automáticamente estos datos históricos, por lo que no necesita ese mantenimiento y será preciso.

Tener clases descriptivas, métodos y nombres de variables . Esto eliminará la necesidad de comentarios como propósito y descripción. A veces pensamos que cuanto más corto sea el nombre del método, mejor. Por el contrario, cree un nombre de método todo el tiempo que desee, siempre que describa claramente su propósito. Solo tenga notas que sean absolutamente vitales y ayuden a la comprensión del código de alguna manera específica. Al realizar cambios en el código, los programadores a menudo olvidan actualizar los comentarios. Puede terminar con comentarios y código que no están sincronizados y hacen más daño que bien.

Lea este artículo de Jeff Atwood - Codificación sin comentarios .

Utilizo etiquetas estándar para generar documentación. Nada más y nada menos. Mira aquí

Nunca pongo información que no pertenece a la clase. Autor, datos, revisiones son datos para almacenar en un sistema de control de versiones.

Los dos formatos presentados son inútiles para generar documentación y tienen el mayor error en los comentarios, enumeran el historial de revisiones.

El repositorio de control de origen puede agregar gran parte de esta información, dejándolo realmente solo con una descripción, que debe describir con precisión el alcance y el comportamiento de la clase. Recomiendo echar un vistazo a algunos de Javadoc para Java JDK como ejemplo.

Todo en esa lista es innecesario. Su control de fuente debe ocuparse de casi todo, y lo que no cubre se ocupa de las convenciones de nomenclatura.

Si tengo que leer su "Descripción" para averiguar qué está haciendo su clase, entonces (a) la nombraron mal o (b) escribió una clase mala que está haciendo demasiado (SRP).

He estado jugando a cambiar mis plantillas de encabezado ya que, como otros señalan, se puede encontrar mucha de esta información en el repositorio y hasta ahora los grandes campos que he estado buscando son los siguientes:

• Descripción : qué está haciendo el código.
• Notas : todo lo que se necesita saber sobre el código que no se deriva fácilmente de los comentarios en el código mismo.
• Referencias : las referencias de las que depende el código no se aclaran a través del uso de includeo declaraciones similares.

Un elemento que también puede ser útil para incluir es una sección sobre palabras clave Si bien es posible que pueda hacer una búsqueda de nombres de funciones, clases, estructuras, etc., puede haber algunas palabras clave que los otros nombres en el archivo no aclaran. O para un código antiguo y mal documentado, podría ser el primer paso para documentar el código para el mantenimiento.

La mayoría de las otras respuestas que leí hasta ahora suponían que solo hay un repositorio que siempre está disponible

Como el código fuente puede perder la conexión con el repositorio (es decir, si se copia), la documentación de mi clase es así:

• class documentation header (= el bloque de comentarios al comienzo del archivo) solo contiene información legal requerida (es decir, copyright de xyz bajo licencia gpl)
• todo lo que un desarrollador que usa la clase debe saber debe ir a la clase-java-doc-comments (o el equivalente de .net) para que los ide-s modernos puedan mostrar esta información como información sobre herramientas en el código fuente que usa la clase.

También puede agregar el número de boleto para la corrección de errores o la solicitud de función para que pueda tener una idea de dónde / cuándo / por qué se creó la clase (si tiene la suerte de que aún pueda acceder a los boletos después de unos años).

Cuando se me pidió que solucionara problemas en viejos programas de código fuente antiguo, los números de los tickets eran muy valiosos para que entendiera los requisitos originales del código.