¿Agrega información al principio de cada archivo .hpp/.cpp?

Question

Al crear un nuevo archivo de cabecera/fuente C++, ¿qué información agrega a la parte superior? Por ejemplo, ¿agrega la fecha, su nombre, una descripción del archivo, etc.? ¿Utiliza un formato estructurado para esta información?

p. Ej.

// Foo.cpp - Implementation of the Foo class 
// Date: 2008-25-11 
// Created by: John Smith 

Uno de los equipos que sé incrusta en el CVS mensajes al pie de cada archivo, pero no estoy seguro de que quiera ir tan lejos ...

Answer 1

Información sobre quién creó un archivo y cuándo y quién lo editó y cuándo todo está en control de fuente. Si su equipo tiene buenas prácticas sobre los comentarios de check-in, sabrá las razones de cada cambio también. No hay necesidad de comentarios para esas cosas.

Creo que es 100% legítimo, incluso - para poner un bloque de comentarios, el tiempo que sea necesario, explicando el propósito de la clase/módulo. Cuando la siguiente persona vaya a cambiarlo, tendrán una mejor idea de la visión general y de si este archivo es el lugar apropiado para su cambio.

Algunas tiendas ponen avisos de derechos de autor y otras carpetas legales en los comentarios del archivo fuente. Esto me parece simplemente una tontería: si su código fuente (que no es OSS) ha ingresado en los servidores de otra persona sin su conocimiento o permiso, un aviso de copyright probablemente no los disuadirá de hacer algo con él. IANAL, YMMV.

Answer 2

No insertar la fecha porque es redundante. Si alguien quiere saber la fecha en que se creó un archivo, no confíe en el autor, confíe en su sistema de control de origen. Debe ser la respuesta definitiva para la fecha de creación.

Definitivamente no estoy en contra de incrustar mensajes de verificación. Esos son bastante útiles.

Answer 3

No. La mayoría de las cosas se pueden recuperar del sistema de versiones cuando sea necesario, por lo que es redundante agregar. Eso te dejaría con la descripción del contenido del archivo, pero eso es parte de la documentación de la clase la mayor parte del tiempo (o al menos la documentación del tipo específico).

No hago ninguno de esos, pero una vez más, no me gusta el cruft.

Answer 4

Incluyo el nombre del archivo, una breve descripción del propósito del archivo y una etiqueta $ Id $ para fines de CVS o Subversion. El creador del archivo y la fecha de creación se pueden encontrar al verificar el repositorio, por lo que no es necesario.

El nombre del archivo está incluido porque, dependiendo de lo que esté usando para editar el archivo, eso puede no ser del todo evidente cuando lo está editando. La descripción se puede usar para determinar si un bit de código pertenece al archivo o si se debe mover a otro. Y, por supuesto, $ Id $ le da la última hora de cambio y el último editor.

Incrustar mensajes de check-in solo es útil cuando el mensaje es útil, y solo si el archivo se actualiza de vez en cuando. Incluir cada mensaje simplemente hinchará el archivo hasta el punto en que haya más comentarios que describan los cambios que el código real. Lo mejor es dejar eso en el repositorio también; a menudo es solo una breve línea de comando para obtener el registro de registro del archivo.

Si tiene un sistema de control de revisiones que no puede mantener el historial de movimientos y copias, en ese caso simplemente haga referencia al archivo original y su número de versión. Por supuesto, si está utilizando un sistema que se creó en algún momento de este siglo y no el último, eso no debería ser un problema.

Answer 5

Estamos obligados a poner la información de copyright en la parte superior de cada archivo. Creo que las fechas, los autores y el nombre del archivo son una pérdida de tiempo.

También tenemos nuestro sistema de control de agregación fuente de facturación comentarios en la parte inferior de cada archivo. Inicialmente odié el registro de cambios, pero con el tiempo aprendí a gustarme. Realmente ayuda al fusionar los cambios.

Answer 6

Si está utilizando CVS, revise que es keyword substitutions. Ayudarán a automatizar la incorporación de esa información.

Personalmente pegar esto en la parte superior de todos mis archivos de origen:

// $Id$ 

Otros comentarios informativos lo integrar a ser analizado con Doxygen, si se refieren a algo específico (el archivo, la clase, una tipo, etc.).

Answer 7

usamos nuestra RCS para estampar automáticamente lo siguiente en el archivo:

Derecho de Autor,

nombre RCS archivo,

fecha de cambio,

Autor de la última modificación,

RCS número de revisión

I creo que esto es muy conveniente. Realmente me gusta que el nombre del archivo se rellene automáticamente en cada archivo, ya que hace que la búsqueda de la solución de los archivos sea muy rápida.

Answer 8

i en general, sólo añadir cualquier "información comentario" cuando ... no creo que voy a recordar o no es algo obvio lo que está haciendo o cuando suelto el código fuente y que en realidad quieren que los demás poder usar/aprender de ello.

Answer 9

Normalmente incluyo una descripción del propósito del código que se encuentra en ese archivo. Todo lo demás parece ser manejado en otra parte: fechas y los comentarios de control de código fuente, etc.

Answer 10

Originalmente contestadas aquí, pero que se suprimió: 134249

sólo pondría dos cosas:

• licencias/derechos de autor información
• comentarios requeridos por las herramientas generadoras de documentación (es decir, los comentarios tienen que estar en el encabezado para funcionar; de lo contrario, deberían ir en los archivos de definición)

Cualquier otra cosa es una pelusa innecesaria que no se mantendrá, y eventualmente será peor que nada en absoluto.

En ese momento trabajaba para una gran compañía de defensa, y teníamos estándares de codificación draconianos.Si los seguiste al pie de la letra (y la mayoría de las personas no), la mayoría de tus encabezados estarían compuestos principalmente por esa pelusa sin sentido. Doblemente peor es que se requiere exactamente la misma pelusa para colocarse también en los archivos fuente, lo que significa que dos copias de la pelusa se desactualizan y se vuelven engañosas.

Answer 11

Todo el mundo dice que su control de fuente tendrá la fecha y la información del programador, pero eso no siempre es cierto. Trabajé en una tienda que usaba Source Safe, y estuvo bien hasta que alguien decidió mover un archivo a una ubicación diferente. En ese momento, esencialmente se convirtió en un nuevo archivo según SS, y no existía ninguna historia previa.

Quizás debido a eso, el nombre y la fecha del programador se agregaron automáticamente a la sección de comentarios en la parte superior del archivo. Cuando llegaran a haber más de 10 entradas, eliminaríamos todas las intermedias, dejando solo la fecha original y el autor, y la información actual.

Answer 12

Una declaración de derechos de autor para mi cliente ;-)

Answer 13

Esto es lo que normaly puse en la parte superior de los archivos:

///////////// Copyright © 2008 DesuraNET. All rights reserved. ///////////// 
// 
// Project  : [project name] 
// File  : [file name] 
// Description : 
//  [TODO: Write the purpose of ... ] 
// 
// Created On: 11/12/2008 2:24:07 PM 
// Created By: [name] <mailto:[email]> 
//////////////////////////////////////////////////////////////////////////// 

y puedo configurar una macro en relación a hacer añadiremos y complete la información predeterminada cuando haga un nuevo archivo

Answer 14

Utilizamos MSVC & VSS y tenemos un complemento que agrega cualquier comentario que especifique al registrarse en el archivo que se está marcando como un comentario. Es muy conveniente buscar en la parte superior del archivo CPP el número de ticket de seguimiento de errores para el que se realizó un cambio.

Answer 15

Me gustaba poner palabras clave de control de versiones en el encabezado del archivo. Pero recuperado de esa aflicción. :) Por dos razones:

1. Nadie puso comentarios que de nada sirvan. Siempre terminas mirando las diferencias reportadas por el sistema de control de versiones.
2. Crea una pesadilla al tratar de diferir conjuntos de archivos grandes porque las palabras clave crean diferencias que son la única diferencia en el archivo.

Answer 16

Uso Subversion. Esto es lo que me gusta poner cerca de la cima.

$Id$ 
$HeadURL$ 

Que sustituye la revisión, el último editor y luego la ubicación del archivo en el repositorio. Aunque siempre trabajo con copias de trabajo, esto me permite imprimir/enviar un archivo por correo electrónico y verlo más tarde para saber exactamente de dónde vino. $HeadURL$ especialmente es bueno porque indica en qué proyecto y rama se encuentra el archivo y cómo llegar a él (es agradable con subpaquetes anidados más grandes y similares).

De acuerdo en la inutilidad de los grandes bloques de comentario manual — aunque docstrings/Javadocs se recomiendan — y en anexar automáticamente el registro de confirmación.

Parece que algunos de ustedes están utilizando VCS terribles, si están recibiendo conflictos diffs o merge generados por las palabras clave mismas. Subversion handles it well.