Commenter / Styles de documentation dans le code


9

C'est peut-être une question stupide, mais elle est à l'arrière de ma tête depuis un moment et je ne trouve aucune réponse décente ailleurs.

J'ai un enseignant qui dit que nous devrions énumérer explicitement chaque paramètre avec une description, même s'il n'y en a qu'un. Cela conduit à beaucoup de répétitions:

double MyFunction(const int MyParam);
// Function: MyFunction
// Summary: Does stuff with MyParam.
// Input: int MyParam - The number to do stuff with.
// Output: MyParam with stuff done to it.

Lors de la rédaction de la documentation en code, comment êtes-vous détaillé?


votre exemple est simpliste. En pratique, vous spécifieriez bien plus de contraintes que le type du paramètre, s'il s'agit d'un entier, il doit s'agir d'un entier valant X et Y. Si la valeur de retour est un double, vous pouvez spécifier sa précision. , et de quelles valeurs il peut s'agir (il pourrait exister une fonction qui renvoie exactement 1.01, 2.31 et 5.01!). Soyez plus précis et vous ne verrez pas autant de répétitions ...
Ancien compte

Réponses:


17

Pour commencer, je conviens que la ligne "Fonction:" dans votre exemple est complètement redondante. D'après mon expérience, les gens ont appris à l'école à ajouter ce type de commentaire en ajoutant ce type de commentaire dans leur code de production.

Les bons commentaires ne répètent pas le contenu du code. Ils répondent à la question "Pourquoi?" au lieu de "Quoi?" ou comment?" Ils couvrent les attentes concernant les entrées, ainsi que la façon dont le code se comportera dans certaines conditions. Ils expliquent pourquoi l'algorithme X a été choisi au lieu de l'algorithme Y. En bref, exactement les choses qui ne seraient pas évidentes pour quelqu'un d'autre 1 à la lecture du code.


1: Quelqu'un d'autre qui connaît la langue dans laquelle le code est écrit. N'écrivez pas de commentaires pour enseigner, des commentaires pour compléter les informations.


1
+1, bien que vous vous rappeliez que ce qui est évident pour vous peut ne pas l'être pour un autre programmeur.
Josh K

@Josh: bon point, j'ai donc édité la réponse.
Larry Coleman

@ Larry: Les bons commentaires doivent également inclure quoi: ce qui entre, ce qui sort, et surtout quel type entre et sort.
Joris Meys

@Joris: Ce qui entre et ce qui sort est couvert par les "attentes concernant les entrées" et "comment le code se comportera". Quant au type d'entrée et de sortie, je maintiens ce que j'ai dit plus tôt: "Les bons commentaires ne répètent pas ce qui est dans le code."
Larry Coleman

2
@ Larry: Je préfère le lire dans le commentaire plutôt que de parcourir les déclarations et le code chaque fois que je veux réutiliser une fonction. Une question de style, je suppose, je suis un gars paresseux.
Joris Meys

6

Plusieurs langages ont des fonctionnalités de génération de documents API comme Ruby, Java, C # et C ++ (via un outil en ligne de commande). Quand vous y pensez de cette façon, cela rend l'écriture des documents API beaucoup plus importante. Après tout, cela répond à la question "comment faire ...?" Je ne ferai donc rien de répétitif comme Function: MyFunctionlorsque le nom de la fonction est clair pour tout le monde. Les outils de génération de documents API sont assez intelligents pour le faire pour moi. Cependant, les détails suivants sont utiles, en particulier sur les méthodes / fonctions publiques:

  • Résumé (ce qu'il fait et, le cas échéant, un résumé de la façon de l'utiliser)
  • Liste des paramètres et ce qui est attendu
  • Quelle sera la valeur de retour (sortie)
  • Toutes les exceptions qui peuvent être levées explicitement et pourquoi

Ceux-ci peuvent devenir des outils de référence utiles lorsque vous essayez de déboguer du code. De nombreux IDE utiliseront également les documents API dans leurs info-bulles lorsque vous survolez le nom de la fonction.

Si c'est une langue sans ces fonctionnalités, les commentaires aident, mais pas autant.


Est-il acceptable si la description de la sortie est incluse avec le résumé? Par exemple, Returns the square root of Xdécrit également la valeur de retour.
Maxpm

Oui; ce que les étudiants devraient apprendre est d'utiliser ces fonctionnalités de documentation.
Jeremy

J'aime garder les documents API plus à une abstraction logique si possible. Par exemple, Returns the color for this rayou Returns the requested Message, or null if it can't be found. Mais oui, le résumé est la chair de la documentation de l'API.
Berin Loritsch

3

S'il s'agit d'une méthode d'API publique, alors oui, vous devez fournir une documentation détaillée, en particulier sur les paramètres et le comportement attendu. Beaucoup de gens pensent que cela peut être assoupli pour les méthodes / fonctions privées, YMMV.

Dans l'ensemble, je préfère écrire du code propre (petites méthodes / fonctions qui font une chose et une chose bien) avec des noms de variables raisonnables. Cela rend une grande partie de votre code auto-documenté. Cependant, je documente toujours tous les cas marginaux, les utilisations de la concurrence et les algorithmes complexes.

En bref, pensez à vous-même comme un peu pire à porter à 3h du matin dans 3 mois. Vous vous remercierez pour vos documents publics impressionnants plutôt que de déterminer ce que signifie le paramètre (drapeau booléen) ...


Parfois, les fonctions peuvent avoir un comportement de casse qui diffère de ce que l'algorithme impliquerait. Par exemple, en arrondissant a floatà un entier en ajoutant 0,5 et en prenant le plancher du résultat, le plus grand en float dessous de 0,5 sera arrondi par erreur. Dans de tels cas, il peut parfois être important de distinguer si une fonction doit être définie comme l'arrondi à l'entier le plus proche (ou à l'entier supérieur suivant lorsque deux valeurs possibles sont équidistantes), ou comme l'ajout de 0,5 (éventuellement avec une étape d'arrondi intermédiaire) et prendre la parole du résultat.
supercat

1

C'est similaire à la façon dont la plupart des frameworks -Doc analysent la documentation en code (JavaDoc, PHPDoc, etc.).

Depuis Java, généré automatiquement par IDE:

/**
 * [Description]
 * @param str [Description]
 * @param isCondition [Description]
 * @return [Description]
 */
public int testFunction(String str, boolean isCondition) {
    ...
}

Il s'agit du même format utilisé pour générer la documentation des fonctionnalités du langage intégré - Exemple: http://download.oracle.com/javase/6/docs/api/java/lang/String.html

Ce format est très utile car il montre clairement à tout utilisateur tiers comment s'interfacer avec votre code. Si vos fonctions sont des méthodes privées qui ne sont utilisées qu'en interne, cela peut être un peu inutile - mais je suppose que votre professeur essaie de vous mettre dans une bonne pratique jusqu'à ce que vous ayez tous l'expérience de faire cette distinction.

Le seul élément que je trouve souvent un peu redondant est la description de retour - Habituellement, elle est presque identique à ma description de méthode.


1

Les commentaires ont deux objectifs:

  1. Ils servent à vous rappeler rapidement ce que fait votre code lorsque vous y revenez des mois / années plus tard. De cette façon, vous n'avez pas à relire et analyser votre code pour rafraîchir votre mémoire.
  2. Ils transmettent à d'autres personnes qui lisent ou travaillent avec votre code ce que fait votre code.

Il y a bien sûr BEAUCOUP de façons différentes d'aborder cela, mais plus vous êtes minutieux et cohérent, mieux c'est. Un commentaire efficace prend du temps à apprendre, tout comme une programmation efficace. Gardez à l'esprit qu'il est difficile de voir le point des commentaires à l'école car rien sur lequel vous travaillez n'est jamais assez grand pour le justifier, mais ils essaient juste de vous le présenter. Et généralement, la façon dont on vous apprend à le faire est le style de votre professeur et non une sorte de norme. Développez ce qui vous convient. Et rappelez-vous ... il y a une chose comme un commentaire stupide! :) Exemple:

a += 1; //adds 1 to the value in a

Vraiment? Merci! LOL


0

J'aime la documentation du site Web PHP, j'utilise donc quelque chose de similaire pour mes commentaires en ligne et j'utilise la syntaxe PHPDoc. Voir l'exemple ci-dessous.

/*
* Finds all the locations where you have access to for this client and returns them in an array .
* @author Radu
* @version 1.0
* @param int $id ( The id of the client for which you're requesting access. )
* @param object $db ( A resource of type Mysql, representing a connection to mysql database, if not supplied the function will connect itself. )
* @return array ( Returns array with id's of locations that you are allowed to see, an empty array if you do not have acces to any locations or returns FALSE and triggers a Warning if any error occuread )
* @use array allowed_locations ( $id [, $db] )
*/
function allowed_locations($id, $db=NULL){ ... }

Et comme l'a dit @Larry Coleman, les commentaires en ligne devraient indiquer pourquoi vous avez créé un morceau de code.

$funcResult = SomeFunction();
if(is_array($funcResult))
{    //Beacause SomeFunction() could return NULL, and count(NULL) = 1
    $c = count($funcResult);
} else {
    $c = 0;
}
if($c == 1)
{
 ... 
}else
{
 ...
}

0

Si c'est au service de la génération de Doc, les commentaires verbeux (bien qu'irritants) sont probablement une bonne chose. Bien que vous deviez en faire un objectif d'équipe pour rester au courant des commentaires et les tenir à jour.

Si c'est juste le style de commentaire, j'aurais un problème avec ça. Des commentaires excessifs peuvent tout autant nuire au code que de l'aide. Je ne peux pas compter le nombre de fois où j'ai rencontré des commentaires dans le code qui étaient obsolètes et par conséquent trompeurs. J'ignore généralement les commentaires maintenant et je me concentre sur la lecture du code et des tests du code pour comprendre ce qu'il fait et quelle est l'intention.

Je préfère avoir un code clair et concis non commenté . Donnez-moi des tests avec des affirmations ou des méthodes descriptives et je suis heureux et informé.

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.