¿Qué debo poner en los comentarios del encabezado en la parte superior de los archivos fuente?

Question

Tengo muchos archivos de códigos fuente escritos en varios idiomas, pero ninguno de ellos tiene un comentario estándar en la parte superior (a veces incluso en el mismo proyecto). Algunos de ellos no tienen ningún comentario en el encabezado :-)

He estado pensando en crear una plantilla estándar que pueda usar en la parte superior de mis archivos fuente, y me preguntaba qué campos debería incluir.

Sé que quiero incluir mi nombre y una breve descripción de lo que contiene/hace el archivo. ¿Debo incluir también la fecha de creación? La fecha de la última modificación? El programador que modificó por última vez el archivo? ¿Qué otros campos ha encontrado que son útiles?

Todos los consejos y comentarios son bienvenidos.

Gracias,
Cameron

Answer 1

Fecha de creación, fecha de modificación y autor que los últimos modificados del archivo deben ser almacenados en el software de control de código fuente.

Yo suelo poner:

• El propósito principal del archivo y las cosas dentro del archivo.
• El proyecto/módulo al que pertenece el archivo.
• La licencia asociada con el archivo (y un archivo de LICENCIA en la raíz del proyecto).
• Quién es responsable del fichero (ya sea el equipo, persona, o ambos)

Answer 2

Esos campos útiles que usted ha mencionado son buenas. Quién modificó el archivo y cuándo.

Su software de control de versiones debe permitir la incrustación de palabras clave en los comentarios. Por ejemplo, en CVS, el $ Id $ se resolverá en el archivo, la fecha/hora modificada y el usuario que modificó el archivo. Se mantendrá automáticamente actualizado con cada check-in.

Answer 3

Esto parece ser una práctica moribunda.

Algunas personas aquí en StackOverflow están en contra de los comentarios del código (razonar que el código debe escribirse para ser autoexplicativo) Aunque no iría tan lejos, algunos de los puntos de la multitud antisentido tienen sentido, como el hecho de que los comentarios tienden a estar desactualizados.

Los bloques de comentarios de encabezado sufren estos síntomas aún más. Todas las organizaciones con las que he estado han tenido estos bloques de encabezado, están desactualizadas. Tienen un nombre de autor de algún chico que ya no trabaja allí, una descripción que no coincide con el código (suponiendo que alguna vez lo haya hecho) y una última fecha de modificación, que una vez comparada con el historial de control de versiones, parece haberse perdido su última docena de actualizaciones.

En mi opinión personal, mantenga los comentarios cerca del código. Si desea conocer el propósito y el historial de un archivo de código, use su sistema de control de versiones.

Answer 4

¿Qué campos necesita? Si tiene que preguntar si desea poner alguna información allí, realmente no necesita esa información. A menos que seas forzado, por alguna incompetencia burocrática de tu empleador, no veo por qué deberías buscar más información de la que ya crees que debería estar allí.\

Answer 5

No mencionó que está utilizando un sistema de control de versiones y su comentario en la respuesta de Neil N confirma esto para su código anterior. Si bien el uso de control de versiones es la mejor manera de hacerlo, también he experimentado muchas situaciones en las que el patrocinador del proyecto no pagaría por el código anterior. Si no tiene un historial de cambios centralizado para el proyecto, entonces el historial de cambios puede colocarse en los módulos. Es bueno que esté usando un sistema de control de versiones para su nuevo código.

Your company name 
All rights reserved (c) year - or reference to appropriate license 

Project or library this file is for 

Module it belongs to 

Description of what it contains 

History 
------- 
01/08/2010 - Programmer - version 
    Initial creation. 
01/09/2010 - Programmer - version 
    Change description. 
01/10/2010 - Programmer - version 
    Change description. 

Answer 6

En la mayoría de las organizaciones, todos los archivos fuente tienen que comenzar con un aviso legal. Si tienes mucha suerte, es solo de una sola línea, pero en la mayoría de los casos es un bloque realmente largo de jerga legal. Como resultado, pocas personas alguna vez leen esto. Nuestro ojo simplemente viaja al primer elemento del programa y luego va a su documentación.

Si desea escribir algo, escríbalo en asociación con el elemento de programa más alto, no el archivo.

Cualquier otra información de contabilidad generalmente debe ser parte del control de su versión, no debe mantenerse (mal) en el archivo.

Answer 7

Además del comentario anterior que indica la licencia, el proyecto al que pertenece, etc. También tiendo a poner los requisitos "extraños" en la parte superior también (como "construido con la versión X de la biblioteca Y") usted, o la persona que lo recoge después de que usted no cambiará algo de lo que el programa se basa sin darse cuenta (o, si lo hacen, al menos sabrán qué cambiar de nuevo)

Answer 8

Atrás en 2002, cuando Acababa de salir de la universidad y los trabajos eran pocos y distantes entre sí después de la caída de las punto com, me uní a una empresa de servicios que solía crear software personalizado para sus clientes en Java. Tuve que sentarme en la oficina de un cliente (que era una habitación desvencijada en una subestación eléctrica equipada con una CA para mantener los servidores en funcionamiento), compartir sillas/PC con otros muchachos en el equipo. Los otros ingenieros (si puedo llamarlos ingenieros;) en el grupo solían realizar cambios ad hoc al código fuente, compilan los archivos y los ponen en producción.

• No hay forma de averiguar quién hizo qué cambio.
• No hay forma de averiguar por qué se realizó algún cambio.
• No hay forma de ir a la versión anterior del código, a menos que el ingeniero "recuerde" lo que modificó.
• Copia de seguridad: copie los archivos del servidor de producción, que fueron reemplazados por archivos nuevos.
• Ubicación de la copia de seguridad: directorio principal de la copia del ingeniero sobre los archivos al servidor de producción.

Informes de servidores de producción que van abajo debido a los intentos fallidos de copia sobre los archivos al servidor (se perdió un archivo para ser copiado, copias de seguridad con la pérdida o archivos incorrectos se copian o no todos los archivos que están siendo copiados) eran se reunió con encogimientos de hombros (oh, no, ¿está abajo? veamos qué pasó, hey quién cambió lo que recientemente ...? ummm ...).

Durante esos días, después de pasar varios días frustrantes tratando de averiguar los Quién y los porqués detrás del código, que habían ideado un sistema para comentarios en una lista en la cabecera del archivo fuente que detalló lo siguiente:

1. Fecha del cambio hizo
2. que hizo el cambio
3. ¿Por qué se hizo el cambio

Dos meses más tarde, cuando la lista amenazó con impugnar la Tam e del código fuente en el archivo, el administrador tuvo la brillante idea de obtener un sistema de control de versiones de origen.

Nunca he necesitado poner ningún comentario en los encabezados de los archivos fuente (excepto los avisos de derechos de autor) en ninguna empresa en la que haya trabajado desde entonces. En mi compañía actual, todo lo demás es evidente por completo al mirar el código, o ir al sistema de informes de errores que está integrado con el sistema de control de versiones de origen.

Answer 9

Mucho depende de si está utilizando una herramienta de generación de auto-documentación o no.

Aunque estoy de acuerdo con muchos de los comentarios, si está utilizando JavaDoc u otra herramienta de generación de documentación que depende de los comentarios, obviamente deberá incluir las cosas que quiere ver.

Answer 10

incluir la siguiente información:

• Lo que este archivo es para. Es un conocimiento muy útil y es más importante que cualquier otra cosa. Debe decirle al lector, por qué hay un archivo así, por qué agrupa las funciones en un archivo/paquete/módulo separado y por qué se usan. Tal vez brevemente, una o dos líneas, pero eso debería estar allí.
• Material legal, si es necesario.
• Deje el lugar para los comandos especiales de los editores de consola, como Emacs.
• Agregue comandos especiales que requiera su sistema de auto-documentación.

cosas cosas usted no debe no incluir son

• que creó el archivo
• Cuando se creó
• Quién lo modificó por última vez
• Cuando fue modificada por última vez
• Lo que se agregó con la última modificación

Puede, y debe, recuperarlo a través del sistema de control de versiones, donde se actualiza de forma constante y automática. Por no hablar de que la mayoría de estos puntos son inútiles.