Quoi écrire dans les commentaires d'en-tête d'un fichier de code?

Question

Je viens juste de commencer un nouveau vert-champ de développement de projet, et je suis en train de définir certaines normes. Je sais que beaucoup de code ont des commentaires d'en-tête de chaque fichier de code avec un avis de droit d'auteur et d'autres gumph. Est-ce nécessaire ou utile à la pratique?

Par exemple, je ne pense pas que de mettre le nom de l'auteur ou la date de modification est utile, parce que notre système de contrôle de source des pistes pour nous. D'autre part, un simple avis de droit d'auteur pourrait être utile, ou même une exigence.

À ce point dans le temps, et pour la forseable avenir, nous n'avons pas l'intention de distribuer le code source, de toute façon.

Ce que (le cas échéant) mettez-vous dans l'en-tête de votre fichier de code?

Answer 1

Je n'en ai mis deux choses:

• licence/informations de droits d'auteur
• commentaires requis par la documentation des outils de génération (c'est à dire, les commentaires doivent être dans l'en-tête de travail - dans le cas contraire, ils doivent aller dans les fichiers de définition)

tout le reste est inutile de peluches qui ne sera pas maintenu, et finira par devenir pire que rien du tout.

@robintw - je suis totalement d'accord. Je travaille actuellement pour une grande entreprise de défense, et nous avons le plus draconiennes normes de codage que vous pouvez imaginer. Si vous avez suivi à la lettre (et la plupart des gens ne le font pas), la plupart de vos en-têtes de serait composé principalement de sens des peluches. Doublement pire, c'est que l' exacte même duvet est nécessaire pour être placé dans les fichiers source, ce qui signifie deux copies de la peluche sort de la date et devient trompeuse.

Answer 2

Il y a 10 minutes, j'ai ouvert le fichier de code que je travaille en ce moment. J'ai vu en haut du fichier, avec pas de commentaires que ce soit, et a été brièvement tenté de mettre quelque chose là-bas. Et puis il m'est apparu que, dans les 25 années de la programmation, je doit avoir produit des Téraoctets de commentaire d'en-tête (peut-être pas littéralement), mais n'ayant jamais été utilisé une fois (peut-être pas littéralement, comme dans les années 80 il n'y avait pas d'autre place pour le suivi des modifications).

Aujourd'hui, je donne des fichiers de code des noms significatifs, de sorte que les gens savent ce qu'ils font (prend soin de la description) et j'utilise de contrôle de la source qui me dit qui a changé quoi, quand et pourquoi. Donc, à moins que quelqu'un me dit qu'il veut un commentaire d'en-tête, et ce qui est censé être en elle, il n'est pas dans mon code.

Answer 3

Le standard de Microsoft en-tête ressemble à quelque chose comme ceci;

// <copyright file="AuthenticationType.cs" company="SharpSTS">
// Copyright (c) 2007, 2008 All Right Reserved, http://sharpsts.com/
//
// This source is subject to the Microsoft Permissive License.
// Please see the License.txt file for more information.
// All other rights reserved.
//
// THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY 
// KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
// PARTICULAR PURPOSE.
//
// </copyright>
// <author>Barry Dorrans</author>
// <email>barryd@idunno.org</email>
// <date>2008-06-10</date>
// <summary>Contains a base, abstract class for an AuthorisationPolicyProvider</summary>

Answer 4

Je dirais rien.

Ce genre de choses surtout de ballonnements et est dans la manière,

Si vous souhaitez inclure un permis de l'inclure dans un fichier séparé, j'ai vu dernière édition par observations et commentaires de l'auteur original, ils doivent être manipulés par le contrôle de source.

Garder votre code propre.

Answer 5

S'il vous plaît ne pas aller par dessus bord et de mettre trop d'informations dans l'en-tête. La dernière compagnie pour laquelle je travaillais (qui a écrit le logiciel pour le contrôle des réacteurs nucléaires) a une quantité folle de choses dans la tête de la liste des auteurs, des dates, des mises à jour, les #includes, les noms de variables, les noms de fonction (et les valeurs de retour) - et c'est exactement ce que je me souviens sur le dessus de ma tête!

Tout cela est venu à partir de vieux standards de codage qui ont été développés avant contrôle de code source a été utilisée - mais même avec un bon contrôle de la source, ils ont dit qu'ils ont dû avoir les en-têtes (et les garder à jour) qu'ils n'acceptaient que la bonne piste.