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

13

Estoy buscando un formato de documentación de clase informativa para mis clases de Entidad, Lógica de Negocios y Acceso a Datos.

Encontré los siguientes dos formatos de 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
  • Historial de revisiones

ya que el nombre del espacio de nombres y de la clase estará allí de todos modos.

Hágame saber sus opiniones, qué formato se recomienda y si existe una forma estándar de escribir el historial de revisiones.

    
pregunta CoderHawk 06.10.2010 - 14:50

6 respuestas

18

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

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

¿Sería tedioso buscar en el repositorio cada vez que quiera conocer la otra información? Yo diría que no. ¿Con qué frecuencia te importa quién fue el autor original? ¿O cuando el archivo fue creado por primera vez? Los complementos (como Ankh SVN para Visual Studio) a menudo le permiten hacer clic con el botón derecho dentro del archivo actual y ver el registro de repoistory del archivo, por lo que no es una molestia realmente ver 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.

    
respondido por el David_001 06.10.2010 - 14:56
11

Tenga nombres descriptivos de clases, métodos y variables . Esto eliminará la necesidad de tales 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, haga un nombre de método siempre que lo desee, siempre que describa claramente su propósito. Solo tenga notas que sean absolutamente vitales y ayude a comprender el código de alguna manera específica. Al realizar cambios en el código, los programadores a menudo se olvidan de actualizar los comentarios. Puede terminar con comentarios y código desincronizado y haciendo más daño que bien.

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

    
respondido por el ysolik 06.10.2010 - 16:33
4

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

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

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

    
respondido por el Maniero 06.10.2010 - 18:12
3

Gran parte de esta información puede ser agregada por su repositorio de control de origen, dejándolo 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 los Javadoc para Java JDK como ejemplo.

    
respondido por el Martijn Verburg 06.10.2010 - 14:55
2

Todo en esa lista es innecesario. El control de la fuente debe ocuparse de casi todo, y lo que no cubre se hace cargo de las convenciones de nomenclatura correctas.

Si tengo que leer tu "Descripción" para descubrir qué está haciendo tu clase, entonces (a) la llamaste mal o (b) escribiste una clase mala que está haciendo demasiado (SRP).

    
respondido por el Chris Holmes 06.10.2010 - 18:53
1

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

  • Descripción : qué hace el código.
  • Notas : cualquier cosa que deba conocerse sobre el código que no se deriva fácilmente de los comentarios en el propio código.
  • Referencias : cualquier referencia de la cual dependa el código que no se aclare a través del uso de include o declaraciones similares.

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

    
respondido por el rjzii 06.10.2010 - 15:37

Lea otras preguntas en las etiquetas