¿Firma cada uno de sus archivos de origen con su nombre? [duplicar]

En realidad no, no. Hay un par de razones por las que:

• Su sistema de control de versiones (VCS) ya almacena estos metadatos . P.ej. cada confirmación en git tiene un campo para el nombre que realizó la confirmación. Los sistemas de control de versiones competentes le permiten ver quién realizó un cambio en una línea específica de código también. Esa funcionalidad generalmente se llama blame , que es un nombre inapropiado, ya que, en lugar de encontrar a alguien con quien culpar , es más útil para encontrar a alguien con quien hablar sobre un problema que tenga en el contexto de el trozo de código).

  He visto algunos comentarios de encabezado que también tienen registro de historial, pero que también pueden extraerse fácilmente de un VCS.

• Desalienta la colaboración de código . "Oye, alguien hizo esto ... tal vez no deberíamos tocar su código". Si no existe una propiedad exclusiva del código en algún archivo de código fuente, mayor será la posibilidad de que alguien más lo cambie, lo que a su vez facilita y habilita la refactorización.

¿Qué pasa con los avisos de derechos de autor?

Aunque por el bien de los derechos de autor, es posible que desee agregar el nombre de la empresa como titular de los derechos de autor en los comentarios del encabezado (también conocido como banner de derechos de autor). Si se trata de un proyecto de código abierto, a menudo es el nombre de la organización mantenedora o solo un mantenedor. Sin embargo, ahora es una práctica común colocar esta información en archivos de texto en la raíz del proyecto. Puedes ver estos archivos de texto realizados en proyectos de código abierto con nombres como README , LICENSE y / o CONTRIBUTORS .

¿Qué pasa con los scripts de base de datos?

Podría argumentar que necesita hacer registros de historial en comentarios de encabezado con scripts SQL de base de datos, aunque últimamente con herramientas de migración de base de datos se ha convertido en una práctica obsoleta. Las herramientas de migración de la base de datos por lo general hacen un seguimiento de las migraciones que se ejecutaron y pueden hacer reversiones según sea necesario. Estas herramientas son más flexibles de usar que un archivo de texto.

No hago esto, específicamente como dijiste porque está rastreado en el control de origen. Cada vez que la información como esta se guarda en dos lugares (control de origen y el archivo en sí mismo como dijiste), quedarán desincronizados . Dado que el control de fuente agrega automáticamente la información, no creo que haya ninguna razón para incluirla directamente.

Dicho esto, si hay algo que no es obvio que está agregando, o puede justificar una discusión adicional, creo que vale la pena agregar comentarios en torno a un bloque de código que indique el cambio realizado y por qué con su nombre.

Sí, firmo mi código. Estoy orgulloso de producir un trabajo de calidad.

  

¿Debería también estar firmando los archivos con los que trabajo por otros motivos? Hacer   ¿tú? Si es así, ¿por qué?

Hay una razón para poner tu nombre en tus archivos. El libro "El programador pragmático" lo alienta, porque los autores asumen que escribirá un mejor código cuando su nombre esté escrito en él, por lo que puede sentirse orgulloso de su trabajo. Los programadores no querrían firmar códigos desordenados, ¿verdad?

Bueno, aquí es donde la realidad ataca. La mayoría de las veces , solo el autor inicial se encuentra en los archivos y, como han dicho otros aquí, esta información pronto estará desincronizada. Y no evita el código desordenado. La mayoría simplemente ignora el hecho de que su nombre aparece en el encabezado del archivo. Este no es un consejo muy pragmático, de un excelente libro, aunque para algunas personas puede hacer una diferencia.

Otra razón para mantener su nombre en los archivos es cuando desea publicar el código fuente, por ejemplo, para un proyecto de código abierto. Esto puede verse como una especie de anuncio.

Pero en la mayoría de los casos, esta información es simplemente un ruido redundante.

git blame (o svn blame si debe) es una herramienta mucho mejor para deducir la "propiedad" del código que una sola línea en la parte superior de un archivo, especialmente después de que un proyecto haya crecido unos cuantos bigotes.

No, no lo hago. Sin embargo, se incluyen todos los encabezados obligatorios (un comentario de encabezado estándar de la empresa en particular es parte de las pautas de estilo de codificación), por lo que si lo requieren como parte de ellos, lo haría. Si no tiene estilos de codificación de proyecto, programa o empresa, entonces debería, y cualquier comentario de encabezado de archivo obligatorio debe estar claramente definido.

Como dijiste, el control de versión debería estar gestionando esto. Cuando otras personas tocan el archivo, ¿se supone que deben actualizar un campo que el control de versiones ya ha rastreado automáticamente, que identifica exactamente qué se cambió y quién realizó el cambio entre cada versión? Eso parece una sobrecarga, especialmente si un desarrollador se olvida de actualizar eso y los futuros desarrolladores van por el encabezado en lugar de buscar en el control de versiones.

Lo hago. La razón no es porque quiero "poseerla" de alguna manera, poniendo mi nombre en ella. Si alguien quisiera editar esa línea, me importaría menos. Y decir que el control de versiones almacenará mis datos es cierto, y sin embargo no tiene sentido si alguien no tiene acceso a mi repositorio.

Trabajo para una gran corporación, y mi código vaga de unidad de negocio a unidad de negocio. El pobre imbécil que obtiene el código de un chico, que lo obtuvo de otro chico, que lo obtuvo de mi jefe idiota, no tendrá la más mínima idea de a quién pedir ayuda a menos que deje un indicio en el código mismo.

Y, como no espero quedarme aquí para siempre, les dejo la información de contacto de real , para que la gente pueda contactarme después de dejar mi trabajo actual si necesitan algo. Es solo cortesía.

¿Por qué querría un comentario con el nombre de alguien en su código fuente?

Si no ofrece información sobre la intención del código y, a menos que se esfuerce por recordar, su nombre no tiene ningún valor en absoluto.

Se eliminaría en la próxima confirmación si lo encontrase.

Por supuesto, los comentarios son generalmente un olor en sí mismos, pero ese es otro tema :)

Mi IDE coloca automáticamente los nombres de usuario en la parte superior de los archivos cuando creas una nueva clase. Es un poco molesto en realidad, porque simplemente ignoramos ese encabezado.

hm, tal vez deberíamos instituir un nuevo estándar de codificación en el que todos tengan que desactivar eso en las preferencias de su IDE y / o eliminar el encabezado automático ...

En mi empresa, usamos un encabezado estandarizado con una nota de copyright para el nombre de nuestra empresa y campos clave para el control de versiones, como Revisión, Fecha, Id.

Es estándar para nosotros poner nuestro nombre en el código fuente y, además, si lo modificamos, marcar esos cambios con un número de cambio y nuestro nombre con ese número de cambio.

TBH, este es el tipo de cosas que habría esperado ver en los estándares de codificación internos.

Creo que no es un mal hábito.

Otros argumentan que VCS lo hará por usted. Bueno, hasta cierto punto, eso es cierto.

Sin embargo, si libera el código bajo un copyleft débil (MIT o lo que sea), casi puede apostar que alguien integrará una instantánea de su código en su base de código y realizará sus propias modificaciones. No podrán distinguir la diferencia entre los comentarios originales y los comentarios de la persona que realizó el check-in original.

Lo mismo se aplica cuando las bases de código se mueven a otros VCS (por ejemplo, de CVS a git). Realmente no se puede saber si todos los metadatos se convertirán en el nuevo VCS (espero que haya alguna forma de migrarlo).

Entonces, para responder a la pregunta:

Cuando agrega un valor significativo al conocer al autor de un fragmento de código (lo que no siempre es así), agregar un autor directamente al archivo de origen es una buena idea. Eso no significa que deba documentar y firmar cada cambio que realice en un archivo fuente.

Estoy seguro de que obtendré puntos negativos aquí.

Coloco mi nombre en los archivos que he creado. También incluyo el nombre y la dirección de la empresa, una declaración de derechos de autor, una descripción del propósito del archivo, el NOMBRE original del archivo (en el archivo) y un breve historial de las revisiones más importantes.

¿Por qué hago esto?

1. El nombre de la empresa, la dirección y la declaración de derechos de autor hacen que sea muy fácil de presentar en el tribunal, en caso de que sea necesario, y muestre la fecha / hora de creación, propiedad, etc. con el propósito de derechos de autor. Sin esa información EN EL ARCHIVO usted confía en el humo y los espejos para convencer a un juez que no sabe nada sobre el software o VCS.

2. Poner el nombre del autor original en el momento de la creación es cuestión de responsabilidad. Si su VCS da la misma información, eso es bueno, pero no está en su cara. Si la cosa se cambia más tarde y alguien agrega errores, el VCS cuenta la historia. Si estás orgulloso de tu trabajo, no te escondas. [Una serie de compañías comerciales requieren este tipo de cosas también por motivos de responsabilidad simples.]

3. Pongo el nombre del archivo en el archivo porque estas cosas cambian. Es un dolor actualizar esto cuando el nombre cambia, y ya no estoy seguro del valor. Sin embargo, ayuda a unir la imagen completa cuando se mira la fuente.

4. Cada archivo tiene un resumen en un párrafo o 2 de su propósito. Si un archivo de origen no tiene ningún propósito, no lo cree. Si tiene un propósito, dígame lo que es: NO ME HAGA QUE GUIRE . Aproximadamente el 95% de todo el código fuente abierto que aparece no tiene un propósito establecido en los archivos fuente y esto me vuelve loco. No quiero adivinar el propósito del nombre del archivo o del contenido, para gritar en voz alta, dígame. No poner en un propósito es simplemente la pereza. (Y no actualizar el propósito también es la pereza).

5. Pre VCS Solía poner un historial completo en los comentarios al comienzo. Post VCS Hice esto por un tiempo también. Muestra el historial en el archivo sin tener que ir a cavar en ningún otro lugar. Sin embargo, es un dolor , así que haz esto y valor bajo. Usa tu historial de VCS para esto. Pero en los encabezados, si realiza un cambio importante (refactorización enorme, reutilización, etc.), haga una nota para el beneficio de los demás. (Y al igual que el autor original, póngalo en su nombre). Por supuesto, se trata de un juicio acerca de qué es importante y qué no lo es. Pero esto es una cortesía para los que te persiguen.

También tengo comentarios extensos en el archivo que establecen qué hacen las cosas: los comentarios, por ejemplo, sobre interfaces, API, encabezados, son esenciales para que un usuario de su API o función o método sepa lo que está pasando, y especialmente cualquier Notas especiales o efectos secundarios.

Dentro del código, los bloques principales obtienen un comentario que describe lo que hace ese bloque. Esto permite una lectura del código para la intención, rápidamente, sin tener que profundizar en el detalle sangriento de una variable declarada 15 páginas antes. (Dígame lo que hace, y por qué . No me diga cómo . Puedo averiguar cómo hacerlo con el código).

Según lo que veo de otros que dejan comentarios aquí, parecería que muchos de ellos eliminarían aproximadamente el 90% de los comentarios que escribo. La vergüenza ... se suma a la entropía del universo.

La única razón para poner su nombre en la parte superior de un archivo es cuando se trata de una tarea y su profesor lo requiere para saber qué estudiante escribió el código que está viendo en una copia impresa.