Que dois-je inclure dans mon en-tête de documentation de classe

Je recherche un format de documentation de classe informatif pour mes classes Entité, Logique d'entreprise et Accès aux données.

J'ai trouvé deux formats d' ici

Format 1

///-----------------------------------------------------------------
///   Namespace:      <Class Namespace>
///   Class:          <Class Name>
///   Description:    <Description>
///   Author:         <Author>                    Date: <DateTime>
///   Notes:          <Notes>
///   Revision History:
///   Name:           Date:        Description:
///-----------------------------------------------------------------

Format 2

// ===============================
// AUTHOR     :
// CREATE DATE     :
// PURPOSE     :
// SPECIAL NOTES:
// ===============================
// Change History:
//
//==================================

Je pense que les éléments de base sont les suivants

• Auteur
• Date de création
• La description
• Historique des révisions

comme espace de noms et nom de classe seront là de toute façon.

Veuillez me faire part de vos réflexions, quel format est recommandé et s'il existe un moyen standard d'écrire l'historique des révisions?

La plupart des informations que vous avez suggérées se trouveraient dans le référentiel source.

La seule chose dont vous avez vraiment besoin est la section des objectifs, qui indique à quoi sert la classe.

Serait-il fastidieux de regarder dans le référentiel chaque fois que vous souhaitez connaître les autres informations? Je dirais non. À quelle fréquence vous souciez-vous de l'auteur original? Ou quand le fichier a été créé pour la première fois? Les plugins (tels que Ankh SVN pour Visual Studio) vous permettent souvent de cliquer avec le bouton droit dans votre fichier actuel et d'afficher le journal de répertoire du fichier, donc ce n'est pas si compliqué de voir ces informations.

De plus, si vous stockez l'historique des versions dans un commentaire, ce commentaire doit être conservé. Au fil du temps, il y a une chance que cela vous ment. Le référentiel de code source conserve automatiquement ces données historiques, n'a donc pas besoin de cette maintenance et sera précis.

Avoir des noms de classe, de méthode et de variable descriptifs . Cela éliminera le besoin de commentaires tels que le but et la description. Parfois, nous pensons que plus le nom de la méthode est court, mieux c'est. Au contraire, faites un nom de méthode aussi longtemps que vous le souhaitez tant qu'il décrit clairement son objectif. Ne contiennent que des notes qui sont absolument essentielles et aident à comprendre le code d'une manière spécifique. Lors de modifications du code, les programmeurs oublient souvent de mettre à jour les commentaires. Vous pouvez vous retrouver avec des commentaires et du code désynchronisés et faire plus de mal que de bien.

Lisez cet article de Jeff Atwood - Codage sans commentaires .

J'utilise des balises standard pour générer de la documentation. Ni plus ni moins. Vois ici

Je ne mets jamais d'informations qui n'appartiennent pas à la classe. Auteur, données, révisions sont des données à stocker sur un système de contrôle de version.

Les deux formats présentés sont inutiles pour générer de la documentation et a la plus grosse erreur sur les commentaires, ils listent l'historique des révisions.

Une grande partie de ces informations peuvent être ajoutées par votre référentiel de contrôle de code source, vous laissant vraiment uniquement avec une description, qui devrait décrire avec précision la portée et le comportement de la classe. Je recommanderais de jeter un œil à certains des Javadoc pour le Java JDK comme exemple.

Tout dans cette liste est inutile. Votre contrôle de source doit prendre en charge presque tout, et ce qu'il ne couvre pas est pris en charge par de bonnes conventions de dénomination.

Si je dois lire votre "Description" pour comprendre ce que fait votre classe, alors (a) vous l'avez mal nommée ou (b) vous avez écrit une mauvaise classe qui en fait trop (SRP).

J'ai essayé de changer mes modèles d'en-tête car, comme d'autres le soulignent, beaucoup de ces informations peuvent être trouvées dans le référentiel et jusqu'à présent, les grands champs que j'ai cherché à conserver sont les suivants:

• Description - Que fait le code.
• Notes - Tout ce qui doit être connu sur le code qui n'est pas facilement dérivé des commentaires dans le code lui-même.
• Les références - Toutes les références dont dépend le code qui ne sont pas clairement expliquées par l'utilisation includeou des déclarations similaires.

Un élément qui peut également être utile à inclure est une section sur les mots-clés Bien que vous puissiez rechercher des noms de fonction, de classe, de structure, etc., il peut y avoir des mots-clés que les autres noms du fichier ne clarifient pas. Ou pour un code plus ancien et mal documenté, cela pourrait être la première étape de la documentation du code pour la maintenance.

La plupart des autres réponses que j'ai lues jusqu'à présent supposaient qu'il n'y a qu'un seul référentiel qui est toujours disponible

Étant donné que le code source peut perdre la connexion au référentiel (c'est-à-dire s'il est copié), ma documentation de classe se présente comme suit:

• class documentation header (= le bloc de commentaires au début du fichier) ne contient que les informations légales requises (ie copyright par xyz sous licence gpl)
• tout ce qu'un développeur qui utilise la classe devrait savoir devrait aller dans la classe-java-doc-comments (ou l'équivalent .net de celui-ci) afin que les idé-s modernes puissent afficher ces informations comme info-bulles dans le code source qui utilise la classe.

Vous pouvez également ajouter le numéro de ticket pour le correctif de bogue ou la demande de fonctionnalité afin que vous puissiez avoir une idée où / quand / pourquoi la classe a été créée (si vous avez la chance de pouvoir accéder aux tickets après quelques années).

Lorsqu'on lui a demandé de résoudre des problèmes dans d'anciens programmes hérités de sources fermées, les numéros de ticket étaient très utiles pour que je comprenne les exigences originales du code.