Documentation du code: combien c'est trop?
https://stackoverflow.com/questions/288298
-
08-07-2019 - |
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
RussianQuestion
Combien de documentation de code dans votre source .NET est trop?
Un peu d’arrière-plan: j’ai hérité d’une grande base de code dont j’ai parlé dans certaines des questions que j’ai posées ici sur SO. L’une des "fonctionnalités" de cette base de code est une classe divine, une classe statique unique comprenant> 3000 lignes de code englobant plusieurs dizaines de méthodes statiques. Tout va de Utilities.CalculateFYBasedOnMonth () à Utilities.GetSharePointUserInfo () à Utilities.IsUserIE6 () . C’est un bon code que n'a pas besoin d'être réécrit , mais simplement refactorisé dans un ensemble approprié de bibliothèques. Je l'ai prévu.
Comme ces méthodes sont en train de passer à une nouvelle couche de gestion et que mon rôle dans ce projet est de préparer le système à la maintenance par d'autres développeurs, je songe à une documentation de code solide. Bien que ces méthodes aient toutes de bons commentaires en ligne, elles n’ont pas toutes un code doco bon (ni aucun) sous la forme de commentaires XML. En utilisant une combinaison de GhostDoc et Sandcastle (ou Document X), je peux créer une documentation HTML plutôt agréable et la publier sur SharePoint, ce qui permettrait aux développeurs de mieux comprendre ce que fait le code sans naviguer dans le code lui-même.
Plus la quantité de documentation contenue dans le code augmente, plus il devient difficile de naviguer dans le code. Je commence à me demander si les commentaires XML rendront le code plus difficile à gérer que, par exemple, un // commentaire plus simple sur chaque méthode.
Ces exemples sont de l'exemple Document X :
/// <summary>
/// Adds a new %Customer:CustomersLibrary.Customer% to the collection.
/// </summary>
/// <returns>A new Customer instance that represents the new customer.</returns>
/// <example>
/// The following example demonstrates adding a new customer to the customers
/// collection.
/// <code lang="CS" title="Example">
/// CustomersLibrary.Customer newCustomer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith");
/// </code>
/// <code lang="VB" title="Example">
/// Dim newCustomer As CustomersLibrary.Customer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith")
/// </code>
/// </example>
/// <seealso cref="Remove">Remove Method</seealso>
/// <param name="Title">The customers title.</param>
/// <param name="FirstName">The customers first name.</param>
/// <param name="MiddleInitial">The customers middle initial.</param>
/// <param name="LastName">The customers last name.</param>
public Customer Add(Title Title, string FirstName, string MiddleInitial, string LastName)
{
// create new customer instance
Customer newCust = new Customer(Title, FirstName, MiddleInitial, LastName);
// add to internal collection
mItems.Add(newCust);
// return ref to new customer instance
return newCust;
}
Et:
/// <summary>
/// Returns the number of %Customer:CustomersLibrary.Customer% instances in the collection.
/// </summary>
/// <value>
/// An Int value that specifies the number of Customer instances within the
/// collection.
/// </value>
public int Count
{
get
{
return mItems.Count;
}
}
Je me demandais donc de votre part: documentez-vous tout votre code avec des commentaires XML dans le but d'utiliser quelque chose comme NDoc (RIP) ou Sandcastle? Si non, comment décidez-vous ce qui va obtenir de la documentation et ce qui ne l’est pas? Un peu comme une API aurait évidemment de la doco, mais qu’en est-il d’une base de code que vous allez confier à une autre équipe à maintenir?
Que pensez-vous que je devrais faire?
La solution
Je pense qu’une bonne partie du problème réside dans la syntaxe de documentation XML verbeuse et cruelle que MS nous a imposée (JavaDoc n’était pas bien meilleur non plus). La question de savoir comment la formater est, dans une large mesure, indépendante de ce qui est approprié.
L'utilisation du format XML pour les commentaires est facultative. Vous pouvez utiliser DOxygen ou d'autres outils reconnaissant différents formats. Ou bien écrivez votre propre extracteur de documents - ce n’est pas aussi difficile que vous le pensiez de faire un travail raisonnable, c’est une bonne expérience d’apprentissage.
La question de savoir combien est plus difficile. Je pense que l'idée d'un code auto-documenté est bonne, si vous creusez pour maintenir du code. Si vous n'êtes qu'un client, vous ne devriez pas avoir besoin de lire le code pour comprendre le fonctionnement d'une fonction donnée. Bien entendu, les types de données et les noms impliquent de nombreuses informations, mais beaucoup ne le sont pas. Par exemple, passer une référence à un objet vous indique ce qui est attendu, mais pas comment une référence nulle sera traitée. Ou, dans le code de l'OP, comment sont gérés les espaces au début ou à la fin des arguments. Je crois qu’il existe beaucoup de plus en plus de ce type d’informations qui devraient être documentées par rapport à ce qui est généralement reconnu.
Pour moi, une documentation en langage naturel est nécessaire pour décrire l'objectif de la fonction, ainsi que toutes les conditions préalables et postérieures à la fonction, ses arguments et les valeurs renvoyées qui ne peuvent pas être exprimées via la syntaxe du langage de programmation .
Autres conseils
Personne n'a mentionné que votre code n'a pas besoin d'être gonflé. La documentation XML peut être dans un autre fichier:
/// <include file="Documentation/XML/YourClass.xml" path="//documentation/members[@name='YourClass']/*"/>
Ensuite, votre méthode Add ne peut contenir aucun commentaire / XML supplémentaire, ni si vous préférez, le résumé (fusionné avec le fichier séparé).
Il est bien plus puissant que le format ordures que sont Javadoc et les dérivés que vous trouvez en PHP / Javascript (bien que Javadoc ait ouvert la voie à la syntaxe XML). De plus, les outils disponibles sont de loin supérieurs et l'apparence par défaut des documents d'aide est plus lisible et plus facile à personnaliser (je peux le dire en ayant écrit des doclets et comparé ce processus à Sandcastle / DocProject / NDoc).
Vous créez un fossé critique entre ceux qui vont gérer les nouvelles bibliothèques et ceux qui vont les consommer.
Si j'écris une nouvelle application et que je vais utiliser ces bibliothèques standard, je devrais obtenir un binaire stable des bibliothèques et les importer simplement dans mon application, sans copier le code source depuis un emplacement et causer potentiellement des problèmes. si le code est modifié. Dans ce cas, je n’aurai accès à aucun des "documents auto-documentés". Des fonctionnalités autres que le nom de la méthode et les paramètres d'entrée / sortie, et même ceux-ci ne seront pas exposés si j'utilise un type d'IDE qui n'a pas la fonctionnalité de complétion automatique activée.
Donc, dans votre exemple de code ci-dessus, je pense que tout va bien. Les choses ne sont pas trop verbeuses dans le code lui-même et les noms sont auto-documentés. D'un autre côté, toutes les données de résumé / paramètres nécessaires sont présentes, de sorte qu'une documentation solide puisse être construite pour permettre aux utilisateurs de la bibliothèque d'avoir toutes les informations critiques à portée de main. Malheureusement, XML est plutôt encombré, mais en gros, je pense que la plupart des développeurs peuvent facilement parcourir tous les contenus récapitulatifs et consulter le code réel de la méthode.
Jeff a un très bon article sur commenter (ou devrais-je dire, pas commenter) ici ...
http://www.codinghorror.com/blog/archives/001150.html
Je sais qu'il semble que je ne réponde pas à la question, mais j'estime que le code doit être valide, il devrait être aussi auto-documenté que possible.
J'ai tendance à documenter toutes les méthodes publiques dans mon propre code; utiliser GhostDoc rend cela trivial. Et afin de réduire l'encombrement lors de la modification de mon code source, je réduis généralement les commentaires en commençant par le mode "Contour". (c.-à-d. utilisez la commande Outline > Réduire en définitions de Visual Studio).
Je n'ai jamais essayé Sandcastle, mais j'apprécie vraiment le confort apporté par Intellisense aux méthodes que j'ai commentées en XML.
J'opte toujours pour les commentaires au format XML / Javadoc, car j'aime pouvoir parcourir la documentation de l'API dans un format sensible (HTML en général).
Cela devient un problème pour parcourir le code source réel, mais j'estime qu'il s'agit en général d'un problème mineur, car Visual Studio est généralement assez intelligent pour réduire les commentaires XML si nécessaire.
Ne vous répétez pas.
- Le premier exemple devrait avoir un meilleur nom de méthode et aucun commentaire.
- Le deuxième exemple ne doit pas contenir de commentaire.
Le nom de la première méthode doit indiquer qu'un nouvel objet est alloué.
Si ce comportement est standard dans l'ensemble de la structure pour chaque ajout, il doit être documenté à un niveau supérieur, pas dans cette documentation API API. Sinon, changez le nom.
Les commentaires doivent ajouter des informations, pas les cacher dans le bruit. Et il devrait y avoir des commentaires, si nécessaire en XML. Et où ils ajoutent de la valeur.
Je ne veux pas voir: " renvoie le nombre " pour une méthode nommée count.
Toutes les fonctions publiques doivent être clairement compréhensibles par une personne familiarisée avec votre base de code, mais PAS dans votre section spécifique sans avoir à fouiller dans le code.
Si vous devez écrire une courte ligne pour expliquer le rôle d’une fonction, il est probable que vous ayez mal nommé votre fonction / vos classes. Le nom doit être explicite dans ce cas
S'il faut plus d'une phrase brève pour l'expliquer, c'est probablement un bon commentaire
S'il faut un paragraphe, votre fonction en fait probablement trop, en plus de noms probablement peu clairs.
Il est généralement préférable de ne pas prendre en compte les commentaires SI VOUS ASSUREZ-VOUS QU'ILS SONT EXACTS . Les commentaires inexacts et / ou incontrôlables sont pires que l'absence de commentaires
Donc, appliquez ces règles:
Dans votre premier exemple: " // créer une nouvelle instance de client " est redondant. Le code est limpide. Les autres commentaires sont parfaits. Ils clarifient ce sur quoi le code fonctionne / quels sont ses résultats
Dans votre deuxième exemple, les commentaires sont des efforts inutiles et rendent la lecture difficile. Tout ce que vous avez à faire est de donner à la fonction un nom propre. Pas si vague "compter". C'est une mauvaise désignation.
J'ai récemment mené une étude qui montre que si vous avez d'importantes "directives", par exemple, l'appelant doit faire X " Dans de nombreuses spécifications (par exemple, "cette méthode utilise X, ce qui signifie Y et Z"), il existe un risque très élevé que vos lecteurs ne se conforment pas aux directives. En fait, quand ils voient une longue documentation, ils la lisent complètement.
Donc, au moins, séparez les éléments importants ou utilisez le balisage (demandez-moi si vous utilisez Java).
Tout dépend des normes utilisées par votre société, mais pour mon équipe, nous documentons en haut de chaque fonction, comme dans votre deuxième exemple (ce que vous pouvez faire dans Visual Studio 2008 en appuyant sur le bouton "/ "Touchez 3 fois de suite en haut de n'importe quelle sous-fonction ou fonction !!).
Le premier exemple est excessif, en particulier les lignes du bas où chaque ligne est commentée. Cependant, je pense que le contenu de l'en-tête de la fonction pourrait être utile, car nous l'utilisons beaucoup ici. Et cela semble être quelque peu standard par rapport à ce que je peux dire de nombreux autres programmeurs.
J'ai déjà vu des normes de codage interdisant de commenter les surcharges de code et de méthode auto-commentées. Bien que YMMV, cela semble être un bon moyen de s’éloigner de "Field _numberOfCars est un entier qui représente le nombre de voitures" et les commentaires de type "qui mènent à la surpopulation".
Les commentaires dans un en-tête pour générer de la documentation sont une bonne chose. Mettre des commentaires dans le code pour expliquer pourquoi vous faites ce que vous faites est aussi généralement une bonne chose. Mettre des commentaires redondants en paraphrasant ce que vous avez fait n’est pas une bonne chose
Ce que vous avez montré est trop loin. Faites-vous une faveur et supprimez-le!
Le code doit d’abord être auto-documenté, à travers des noms de méthodes et de paramètres significatifs. Dans l'exemple que vous avez montré;
public Customer Add (titre, chaîne FirstName, chaîne MiddleInitial, chaîne LastName) est parfaitement compréhensible pour l’intention de ce qui se passe, tout comme "Count".
Ce commentaire, comme vous l'avez fait remarquer, est purement un bruit autour de ce qui est par ailleurs facile à lire du code. La plupart des développeurs préfèrent ouvrir et examiner le code et l’utiliser, plutôt que de se contenter de la documentation obscure sur les API générée automatiquement. À chaque fois!
Au fait, selon "Nettoyer le code". (Un excellent livre, BTW), il faut éviter d’utiliser des balises HTML / XML dans les commentaires incorporés dans le code source. Même si votre IDE peut créer une documentation astucieuse lorsque vous survolez, cela est considéré comme trop distrayant et illisible lorsque vous parcourez simplement vos sources.
