comments - sirve - ¿Son los encabezados y pies de página de los comentarios realmente necesarios?
encabezado y pie de pagina word 2013 (10)
El requisito del historial de cambios en el encabezado podría ser una sobra antes de que tuvieran un sistema de historial de cambios implementado. ¡He trabajado con sistemas en los que los comentarios se hicieron manualmente y crearía cambios falsos en el sistema de control de origen!
Donde trabajo actualmente, los derechos de autor y el historial de cambios no se requieren en los encabezados o pies de página del archivo de código.
Muchos estándares de codificación corporativa requieren un gran encabezado de comentario y pie de página en todos y cada uno de los archivos. Algo como:
// MyFile.cpp
//
// Copyright (c) 200x Company ABC
//
// This file is a copyrighted... blah blah blah
//
<... some code ...>
// Copyright (c) 200x Company ABC
//
// Change history:
// 1.0 - Blah
// 1.1 - Blah, blah..
Entonces, la pregunta es: ¿por qué necesitamos esto? ¿Es realmente necesario reclamar derechos de autor para los contenidos del archivo, o es una práctica equivocada que se ha convertido en estándar? ¿Alguien trabaja para una compañía que NO requiere algo como esto?
En la empresa en la que tuve mi pasantía, usamos estos encabezados de comentarios estándar en todos los archivos de origen, chico, me molestaron. Cada vez que tenía que leer un nuevo archivo de código fuente, tenía que desplazar 1 o 2 longitudes de pantalla hacia abajo debido a todo el historial de cambios que tenía cada archivo. En los 6 meses que estuve allí, nunca usé el historial de cambios y nunca vi a nadie que lo hiciera.
Mi opinión personal es que no debes colocar cosas que rara vez necesitarás en un lugar así. Debe tener el historial de cambios y cosas así en algún lugar, por supuesto, pero debería estar en algún lugar donde pueda buscar en caso de que realmente lo necesite. Tal vez en el pie de página si insistes en incrustarlo en los archivos de origen?
Los comentarios de encabezado estándar son un dolor, y deben ser MUY minimalistas o incluso mejor no existentes. Tira ese enorme arte ASCII al pie de página o al Léame, no me importa, pero por favor, deja mi encabezado solo :)
¿Crees que Google hubiera sido un éxito si los primeros 800 píxeles de su resultado de búsqueda se rellenaran con un gran logotipo de Google y declaraciones de derechos de autor? :PAG
Es interesante ver que Google require aviso de derechos de autor en su fuente de C ++. Esto siempre me ha parecido superfluo, especialmente dado que los archivos (¡con suerte!) Serán respaldados y también residirán en Source Control, en caso de que se produzca una batalla de derechos de autor. Tampoco estoy seguro de calificar la fuente con el nombre del autor: ¿otras personas necesitan pedir permiso para editar / usar el archivo?
Source Control definitivamente elimina la necesidad de un pie de página en el historial de cambios, y la práctica extraña que he presenciado de personas que comentan el código antiguo y lo dejan allí. El buen software SCM le permitirá navegar por las revisiones de archivos y proporcionar una comparación de versiones de todos modos. Buena pregunta :)
Mi empresa no requiere esto ... y el lugar del historial de cambios debe estar en el control de código fuente en lugar del archivo de código.
Muchas de estas cosas son resaca histórica. Pero eso no significa que sea inútil.
Comentar los cambios en un archivo es bastante inútil, el archivo dejó de ser la unidad de organización de código hace muchos años. Pongo encabezados en mis funciones, pero eso es para explicar el propósito de la función / método (además hace que el código sea más fácil de escanear). También puse historiales de cambios concisos en esos encabezados de funciones ... no porque sea necesario un historial de cambios en el código, sino porque los sistemas SCM no son perfectos, y he visto bases de datos de SCM perdidas anteriormente. Es como copias de seguridad: el desastre solo tiene que sucederle una vez antes de que comience a preocuparse por estas cosas todos los días.
Mis amigos en el trabajo me vuelven loco porque confían religiosamente en el SCM para rastrear sus cambios, pero tampoco ponen los comentarios apropiados en el SCM. Entonces, cuando se produce el inevitable análisis de fallas post-problema de la administración, tienen que quedarse sentados durante horas y horas tratando de averiguar por qué hicieron un cambio dado hace tres años.
No es necesario reclamar los derechos de autor (depende de la jurisdicción). Normalmente tienes los derechos de autor automáticamente para tu trabajo.
Para el código dentro de una cooperación, siempre es bueno saber cómo se hizo qué y cuándo en un archivo de origen.
Nunca he visto código interno sin algún tipo de combinación encabezado / pie de página.
Primero, el historial de cambios no tiene sentido, usa tu SCM para eso.
No se requiere estrictamente una declaración de derechos de autor (los derechos de autor son automáticos) 1 , pero si está publicando una fuente, es probable que su inclusión sea más segura. La declaración de licencia completa probablemente sería mejor en un archivo separado y luego se hace referencia (esto es lo que hace Boost ).
1 Wikipedia tiene un resumen razonable, pero realmente necesita seguir su propio consejo legal.
2 Especialmente por los abogados jugando a lo seguro.
Si esto llega a los estándares corporativos, no lo tenemos en absoluto. Pero a pesar de esto, agregamos la declaración de copyright y los datos de contacto al comienzo de cada archivo cuando se supone que este archivo debe ser distribuido o se supone que está en uso por otras instalaciones. Ayuda en la recopilación de comentarios.
Trabajo en una corporación de software muy grande, con muchos estándares extraños.
Este no es uno de ellos. No estamos obligados a agregar encabezados o pies de página a nuestro código fuente. Los derechos de autor no necesitan indicarse en cada archivo de clase. sin mencionar la revisión, que se maneja con cualquier sistema de administración de control de fuente disponible.
Trabajo en una empresa y no requerimos esto. Tenemos derechos de autor para lo que hacemos de forma predeterminada, por lo que solo es un ruido de texto innecesario en un archivo de origen.
Cambiar la historia puede ser útil pero muy limitado. Si intenta hacer un registro de cada punto y coma o operador que cambia, se volverá viejo muy pronto. Además, el historial de cambios no le brinda muchos detalles sobre qué ha cambiado exactamente un autor en particular. Es más bien quién ha estado aquí e hizo algo.