Commenter / Styles de documentation dans le code

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é?

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 ¹ à 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.}

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.

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) ...

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.

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

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
{
 ...
}

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é.