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?
-
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.
-
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.]
-
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.
-
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).
-
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.