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?
c#
documentation
comments
CoderHawk
la source
la source
Réponses:
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.
la source
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 .
la source
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.
la source
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.
la source
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).
la source
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:
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 source
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)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.
la source