Signez-vous chacun de vos fichiers source avec votre nom?
Duplicata possible:
Comment gardez-vous une trace des auteurs du code?
Un de mes collègues a l'habitude de mettre son nom et son adresse e-mail en tête de chaque fichier source sur lequel il travaille, en tant que métadonnées d'auteur. Je ne suis pas; Je préfère me fier au contrôle de code source pour me dire à qui je dois parler d'un ensemble de fonctionnalités donné.
Dois-je également signer des fichiers sur lesquels je travaille pour d'autres raisons? Le faites vous? Si oui, pourquoi?
Pour être clair, cela s'ajoute aux métadonnées pour les informations de copyright et de licence incluses, et s'applique à la fois au code source ouvert et au code propriétaire.
Non, pas vraiment. Il y a plusieurs raisons pour lesquelles:
Votre système de contrôle de version (VCS) stocke déjà ces métadonnées. Par exemple. chaque commit dans git a un champ pour le nom qui a fait le commit. Les systèmes de contrôle de version compétents vous permettent également de voir qui a effectué une modification sur des lignes de code spécifiques. Cette fonctionnalité est généralement appelée
blame, ce qui est un terme impropre car, au lieu de trouver quelqu'un pour faire du vrai blâme on, il est très utile pour trouver quelqu'un avec qui parler d'un problème que vous avoir dans le contexte du morceau de code).J'ai vu quelques commentaires d'en-tête qui ont également un journal d'historique, mais qui peuvent également être facilement extraits d'un VCS.
Cela décourage la collaboration de code. "Hé, quelqu'un a fait ça ... peut-être qu'on ne devrait pas toucher à son code". S'il n'y a pas de propriété de code unique sur certains fichiers de code source, alors la probabilité que quelqu'un d'autre le modifie est plus élevée, ce qui à son tour facilite et permet la refactorisation.
Qu'en est-il des avis de droit d'auteur?
Cependant, pour des raisons de droit d'auteur, vous souhaiterez peut-être ajouter le nom de l'entreprise en tant que détenteur des droits d'auteur dans les commentaires d'en-tête (aka bannière de droits d'auteur). S'il s'agit d'un projet open source, il s'agit souvent du nom de l'organisation responsable ou d'un seul responsable à la place. Cependant, il est désormais courant de placer ces informations dans des fichiers texte à la racine du projet. Vous pouvez voir ces fichiers texte réalisés sur des projets open source avec des noms tels que README, LICENSE et/ou CONTRIBUTORS.
Qu'en est-il des scripts de base de données?
Vous pourriez affirmer que vous devez créer des journaux d'historique dans les commentaires d'en-tête avec des scripts SQL de base de données, mais ces derniers temps avec les outils de migration de base de données, cela a rendu cette pratique obsolète. Les outils de migration de base de données gardent généralement une trace des migrations qui ont été exécutées et peuvent effectuer des restaurations si nécessaire. Ces outils sont plus flexibles à utiliser qu'un fichier texte.
Je ne fais pas cela, en particulier comme vous l'avez dit car il est suivi dans le contrôle de source. Chaque fois que des informations comme celle-ci sont conservées à deux endroits (contrôle des sources et fichier lui-même comme vous l'avez dit), elles ne seront plus synchronisées. Étant donné que le contrôle de source ajoute automatiquement les informations, je ne pense pas qu'il y ait aucune raison de les inclure directement.
Cela étant dit, s'il y a quelque chose qui n'est pas évident que vous ajoutez, ou peut justifier une discussion plus approfondie, je pense qu'il vaut la peine d'ajouter des commentaires autour d'un bloc de code indiquant la modification apportée et pourquoi avec votre nom.
Oui, je signe mon code. Je suis fier de produire un travail de qualité.
Dois-je également signer des fichiers sur lesquels je travaille pour d'autres raisons? Le faites vous? Si oui, pourquoi?
Il y a une raison pour mettre votre nom dans vos fichiers. Le livre "The Pragmatic Programmer" l'encourage, car les auteurs supposent que vous écrivez un meilleur code lorsque votre nom est écrit dessus, afin que vous puissiez être fier de votre travail. Les programmeurs ne voudraient pas signer des morceaux de code en désordre, n'est-ce pas?
Eh bien, c'est là que la réalité frappe. La plupart du temps, seul l'auteur initial se trouve dans les fichiers et, comme d'autres ici indiqués, ces informations seront bientôt désynchronisées. Et cela n'empêche pas le code désordonné. La plupart ignore simplement le fait que leur nom est répertorié dans l'en-tête du fichier. Ce n'est pas du tout un conseil très pragmatique, d'un livre par ailleurs excellent, bien que pour certaines personnes, cela puisse faire une différence.
Une autre raison de conserver votre nom dans les fichiers est lorsque vous souhaitez publier du code source, par exemple pour un projet open source. Cela peut être vu comme une sorte de publicité.
Mais dans la plupart cas, cette information n'est qu'un bruit redondant.
git blame (ou svn blame si vous devez) est un bien meilleur outil pour déduire la "propriété" du code qu'un simple liner en haut d'un fichier, en particulier après qu'un projet ait augmenté de quelques moustaches.
Pourquoi voudriez-vous un commentaire avec le nom de quelqu'un dans votre code source?
Si n'offre aucun aperçu de l'intention du code et à moins que vous ne vous efforciez de vous souvenir de votre propre nom, je n'ai aucune valeur.
Il serait supprimé lors du prochain commit si je le rencontrais.
Bien sûr, les commentaires sont généralement une odeur en soi, mais c'est un autre sujet :)
Non, non. Cependant, tous les en-têtes obligatoires (un commentaire d'en-tête standard de l'entreprise fait partie des directives de style de codage) sont inclus, donc s'ils l'exigent dans le cadre d'eux, alors je le ferais. Si vous n'avez pas de styles de codage de projet, de programme ou d'entreprise, vous devez le faire, et tout commentaire d'en-tête de fichier obligatoire doit être clairement défini.
Comme vous l'avez dit, le contrôle de version devrait gérer cela. Lorsque d'autres personnes touchent le fichier, sont-elles censées mettre à jour un champ qui est déjà automatiquement suivi par le contrôle de version, qui identifie exactement ce qui a été modifié et qui a effectué le changement entre chaque version? Cela semble juste comme des frais généraux, surtout si un développeur oublie de mettre à jour cela et que les futurs développeurs passent par l'en-tête plutôt que de regarder dans le contrôle de version.
Je fais. La raison n'est pas parce que je veux le "posséder" en quelque sorte, en y mettant mon nom. Si quelqu'un voulait éditer cette ligne, je m'en fiche. Et dire que le contrôle de version stockera mes données est vrai, et pourtant inutile si quelqu'un n'a pas accès à mon référentiel.
Je travaille pour une grande entreprise et mon code passe d'une unité commerciale à une autre. Le pauvre schmuck qui obtient le code d'un gars, qui l'a obtenu d'un autre gars, qui l'a obtenu de mon patron idiot, n'aura pas la moindre idée de qui appeler pour obtenir de l'aide, à moins que je ne laisse un indice dans le code lui-même.
Et, parce que je ne m'attends pas à rester ici pour toujours, je laisse réel informations de contact, afin que les gens puissent me contacter après avoir quitté mon emploi actuel s'ils ont besoin de quelque chose. C'est juste de la courtoisie.
Mon IDE place automatiquement les noms d'utilisateur en haut des fichiers lorsque vous créez une nouvelle classe. C'est en fait assez ennuyeux, car nous ignorons simplement cet en-tête.
hm, peut-être que nous devrions instituer une nouvelle norme de codage où tout le monde doit désactiver cela dans les préférences de leur IDE et/ou supprimer l'en-tête automatique ...
Dans mon entreprise, nous utilisons un en-tête standardisé avec une note de copyright pour le nom de notre société et des champs clés pour le contrôle de version, comme la révision, la date, l'ID
Il est standard pour nous de mettre notre nom dans le code source et de plus, si nous le modifions, de marquer ces changements avec un numéro de changement et notre nom par rapport à ce numéro de changement.
TBH, c'est le genre de chose que je m'attendais à voir dans les normes de codage internes.
Je suis sûr que j'obtiendrai des points négatifs ici.
Je place mon nom dans les fichiers que j'ai créés. J'inclus également le nom et l'adresse de la société, une déclaration de copyright, une description de l'objectif du fichier, le NOM d'origine du fichier (dans le fichier) et un bref historique des principales révisions.
Pourquoi je fais ça:
Le nom, l'adresse et la déclaration des droits d'auteur de la société facilitent la production en justice, si cela s'avère nécessaire, et indiquent la date/heure de création, de propriété, etc. aux fins du droit d'auteur. Sans ces informations DANS LE FICHIER, vous comptez sur la fumée et les miroirs pour convaincre un juge qui ne connaît rien au logiciel ou au VCS.
Mettre le nom de l'auteur original au moment de la création est une question de responsabilité. Si votre VCS donne les mêmes informations, c'est bien mais ce n'est pas dans votre visage. Si la chose est modifiée plus tard et que quelqu'un ajoute des bogues, le VCS raconte l'histoire. Si vous êtes fier de votre travail, ne vous cachez pas. [Un certain nombre de sociétés commerciales exigent également ce genre de chose pour des raisons de responsabilité.]
J'ai mis le nom du fichier dans le fichier parce que ces choses changent. C'est un pain pour mettre à jour cela lorsque le nom change, et je ne suis plus sûr de la valeur. Cependant, cela aide à rassembler l'ensemble de l'image lorsque vous regardez la source.
Chaque fichier a un résumé dans un para ou 2 de son objectif. Si un fichier source n'a aucune utilité, ne le créez pas. Si cela a un but, dites-moi ce que c'est - ne me faites pas deviner. Environ 95% de tout le code open source que je rencontre n'a pas d'objectif indiqué dans les fichiers source et cela me rend fou. Je ne veux pas deviner le but du nom de fichier ou du contenu, pour crier à haute voix - dites-moi. Ne pas mettre dans un but est simplement LA PARESSE. (Et ne pas mettre à jour le but est aussi de la paresse.)
Avant VCS, j'avais l'habitude de mettre un historique complet dans les commentaires au début. Post VCS J'ai aussi fait ça pendant un moment. Il montre l'historique dans le fichier sans devoir creuser ailleurs. Il s'agit cependant d'un douleur alors faites-le, et de faible valeur. Utilisez votre historique VCS pour cela. Mais dans les en-têtes si vous effectuez un changement majeur (refactoring énorme, réutilisation, etc.) - faites une note au profit des autres. (Et comme l'auteur original, mettez votre nom.) Il s'agit bien sûr d'un jugement sur ce qui est majeur et ce qui ne l'est pas. Mais c'est une courtoisie pour ceux qui viennent après vous.
J'ai également de nombreux commentaires dans le fichier qui décrivent ce que les choses font - des commentaires, par exemple sur les interfaces, les API, les en-têtes, sont essentiels pour qu'un utilisateur de votre API ou fonction ou méthode sache ce qui se passe, et en particulier toutes les notes spéciales ou Effets secondaires.
Dans le code, les blocs majeurs obtiennent un commentaire décrivant ce que fait ce bloc. Cela permet une lecture du code intentionnelle, rapidement, sans avoir à fouiller dans le détail sanglant de certaines variables déclarées 15 pages plus tôt. (Dites-moi quoi c'est le cas, et pourquoi. Ne me dites pas comment. Je peux comprendre le comment à partir du code.)
Sur la base de ce que je vois des autres laissant des commentaires ici, il semblerait que beaucoup d'entre eux supprimeraient environ 90% des commentaires que j'écris. La honte ... ajoute à l'entropie de l'univers.
Je pense que ce n'est pas une si mauvaise habitude.
D'autres soutiennent que VCS le fera pour vous. Eh bien, jusqu'à un certain point, c'est vrai.
Si toutefois vous publiez du code sous un copyleft faible (MIT ou autre), vous pouvez presque parier que quelqu'un intégrera un instantané de votre code dans sa base de code et fera ses propres modifications. Ils ne pourront pas faire la différence entre les commentaires originaux et les commentaires de la personne qui a effectué l'enregistrement original.
La même chose s'applique lorsque les bases de code se déplacent vers d'autres VCS (par exemple de CVS à git). Vous ne pouvez pas vraiment dire si toutes ces métadonnées entreront dans le nouveau VCS (je m'attends à ce qu'il y ait un moyen de le migrer).
Donc pour répondre à la question:
Quand il ajoute une valeur significative à connaître l'auteur d'un morceau de code (ce qui n'est pas toujours le cas), l'ajout de l'auteur directement dans le fichier source est une bonne idée. Cela ne signifie pas que vous devez documenter et signer chaque modification que vous apportez à un fichier source.