Google Style Guide en C ++. Partie 9

Partie 1. Introduction
...
Partie 8. Dénomination
Partie 9. Commentaires
...


Cet article est une traduction d'une partie du guide de style Google en C ++ en russe.
Article original (fork sur github), traduction mise à jour .

Commentaires

Des commentaires sont requis pour le code (si vous prévoyez de le lire). Les règles suivantes décrivent ce que vous devez commenter et comment. Mais rappelez-vous: bien que les commentaires soient très importants, le code parfait est auto-documenté. L'utilisation de noms "parlants" pour les types et les variables est bien meilleure que les noms obscurs, qui doivent ensuite être écrits dans les commentaires.

Commentez le code en tenant compte de ses lecteurs suivants: des programmeurs qui ont besoin de comprendre votre code. Gardez à l'esprit que vous pouvez être le prochain lecteur!

Style de commentaire

Utilisez // ou / * * / jusqu'à ce que l'uniformité soit violée.

Vous pouvez utiliser // ou / ** / , cependant // est de loin préférable. Cependant, alignez toujours votre style de commentaire sur le code existant.

Commentaires dans l'en-tête du fichier

Insérez un en-tête de licence en haut de chaque fichier.

Les commentaires dans le fichier doivent décrire son contenu. Si un fichier déclare, décrit ou teste une abstraction (pour laquelle il existe déjà un commentaire), une description supplémentaire dans l'en-tête du fichier n'est pas nécessaire. Sinon, insérez une description du contenu en haut du fichier.

Informations légales et liste des auteurs

Chaque fichier doit contenir des informations de licence. Le format de la description dépend de la licence utilisée dans le projet. Chaque licence (Apache 2.0, BSD, LGPL, GPL, etc.) peut avoir ses propres exigences de conception.

Si vous apportez des modifications importantes au fichier, pensez à supprimer la liste précédente des auteurs. Les fichiers mis à jour ne peuvent plus contenir de mention du droit d'auteur et une liste d'auteurs.

Contenu du fichier

Si .h déclare plusieurs abstractions, le commentaire dans l'en-tête du fichier doit généralement décrire le contenu du fichier et comment les abstractions sont liées les unes aux autres. Une, deux phrases dans un commentaire suffisent généralement. Des informations plus détaillées sont signées ailleurs (pas dans l'en-tête du fichier).

Ne dupliquez pas les commentaires dans les fichiers .h et .cc - les commentaires deviennent différents au fil du temps.

Commentaires de classe

Chaque déclaration de classe (à l'exception des déclarations très évidentes) doit être accompagnée d'un commentaire, à quoi sert la classe et comment l'utiliser.

//   GargantuanTable. // : // GargantuanTableIterator* iter = table->NewIterator(); // for (iter->Seek("foo"); !iter->done(); iter->Next()) { // process(iter->key(), iter->value()); // } // delete iter; class GargantuanTableIterator { ... }; 

Le commentaire sur la classe doit être suffisant pour comprendre: comment et quand utiliser la classe, des exigences supplémentaires pour une utilisation correcte de la classe. Décrivez, si nécessaire, les restrictions (hypothèses) sur la synchronisation dans la classe. Si une instance de la classe peut être utilisée à partir de différents threads, assurez-vous de noter les règles multi-thread.

Vous pouvez également fournir de courts exemples de code dans le commentaire de la classe pour montrer à quel point il est plus facile d'utiliser la classe.

En règle générale, une classe est déclarée / définie dans différents fichiers ( .h et .cc ). Les commentaires décrivant l'utilisation de la classe doivent être à côté de la définition de l'interface. Les commentaires sur les subtilités de l'implémentation doivent être proches du code des méthodes elles-mêmes.

Commentaires sur la fonction

Les commentaires sur une déclaration de fonction doivent décrire l'utilisation de la fonction (sauf dans les cas les plus évidents). Les commentaires sur la définition de la fonction décrivent l'implémentation.

Déclaration de fonction

La déclaration de chaque fonction doit avoir un commentaire (juste avant la déclaration), ce que fait la fonction et comment l'utiliser. Un commentaire ne peut être omis que si la fonction est simple et son utilisation évidente (par exemple, la fonction de soustraction de valeurs de variable). Essayez de commencer les commentaires à titre indicatif («Ouvrir le fichier»). L'utilisation de l'humeur impérative («Ouvrir un fichier») n'est pas recommandée. Un commentaire décrit l'essence d'une fonction, pas comment elle le fait.

Dans le commentaire sur la déclaration de fonction, notez ce qui suit:

• Ce qui est envoyé à l'entrée de la fonction, qui est retourné en conséquence.
• Pour une fonction membre d'une classe: l'instance conserve-t-elle des arguments de référence,
  Dois-je libérer de la mémoire?
• La fonction alloue-t-elle la mémoire que le code appelant doit supprimer.
• Peut-il y avoir des arguments nullptr.
• La complexité de la fonction (algorithmique).
• Les appels provenant de différents threads sont-ils autorisés en même temps? Et la synchronisation?

Un exemple:

 //    .    //   .    //    GargantuanTable  . // //      . // //    : // Iterator* iter = table->NewIterator(); // iter->Seek(""); // return iter; //         , //    NewIterator()     . Iterator* GetIterator() const; 

Cependant, ne mâchez pas les choses évidentes.

Lorsque vous documentez des fonctions surchargées, effectuez les principaux changements tenaces par rapport à la fonction d'origine. Et s'il n'y a pas de changement (ce qui arrive souvent), des commentaires supplémentaires ne sont pas du tout nécessaires.

Lorsque vous commentez des constructeurs et des destructeurs, gardez à l'esprit que le lecteur de code connaît leur objectif. Par conséquent, le commentaire du type "détruit cet objet" est stupide. Vous pouvez décrire ce que le constructeur fait avec les arguments (par exemple, changer la propriété des pointeurs) ou quel type d'opérations de nettoyage le destructeur fait. Si tout est clair, ne commentez rien. En général, les destructeurs n'ont généralement aucun commentaire (lorsqu'ils sont déclarés).

Définition de fonction

S'il y a des astuces dans l'implémentation de la fonction, vous pouvez ajouter un commentaire explicatif à la définition. Vous pouvez y décrire des astuces avec le code, donner un aperçu de toutes les étapes des calculs, expliquer le choix de telle ou telle implémentation (surtout s'il existe de meilleures alternatives). Vous pouvez décrire les principes de la synchronisation du code (ici nous bloquons, mais ici nous emballons le poisson).

Notez que vous ne devez pas répéter le commentaire sur la déclaration de la fonction (à partir d'un fichier .h ou similaire). Il est possible de décrire brièvement ce que fait la fonction, mais l'essentiel devrait être comment elle le fait.

Commentaires sur les variables

Dans le bon sens, le nom de la variable devrait immédiatement dire de quoi il s'agit et pourquoi, mais dans certains cas, des commentaires supplémentaires sont nécessaires.

Membre de données de classe

Le but de chaque membre de la classe doit être évident. S'il y a des subtilités non évidentes (significations spéciales, liens avec d'autres membres, restrictions sur la durée de vie) - tout cela doit être commenté. Cependant, si le type et le nom sont suffisants - vous n'avez pas besoin d'ajouter de commentaires.

En revanche, des descriptions de valeurs spéciales (et non évidentes) (nullptr ou -1) seront utiles. Par exemple:

 private: //       // -1 - ,         int num_total_entries_; 

Variables globales

Toutes les variables globales doivent être commentées sur leur objectif et (si elles ne sont pas évidentes) pourquoi elles doivent être globales. Par exemple:

 //   ,     const int kNumTestCases = 6; 

Commentaires sur la mise en œuvre

Commentez l'implémentation d'une fonction ou d'un algorithme dans le cas de morceaux de code non évidents, intéressants et importants.

Commentaires descriptifs

Les blocs de code complexes ou non standard doivent être précédés d'un commentaire. Par exemple:

 //    2.  x    for (int i = 0; i < result->size(); ++i) { x = (x << 8) + (*result)[i]; (*result)[i] = x >> 1; x &= 1; } 

Commentaires de ligne

Il est conseillé de compléter les lignes de code avec une signification non évidente par un commentaire (généralement situé à la fin de la ligne) Ce commentaire doit être séparé du code par 2 espaces. Par exemple:

 //   ,    mmap_budget = max<int64>(0, mmap_budget - index_->length()); if (mmap_budget >= data_size_ && !MmapData(mmap_chunk_bytes, mlock)) return; //    

Notez qu'il y a 2 commentaires sur le bloc de code: l'un décrit ce que fait le code, l'autre rappelle que l'erreur est déjà dans le journal s'il y a un retour de la fonction.

Commentaires sur les arguments de fonction

Lorsque l'affectation d'un argument à une fonction n'est pas évidente, envisagez les options suivantes:

• Si l'argument est une valeur fixe (constante littérale) et cette valeur
  utilisé dans différents blocs de code (et il est entendu que cette valeur est la même chose)
  vous devez créer une constante et l'utiliser explicitement.
• Vous devriez peut-être remplacer l'argument de type bool par
  énumération énumération. Cela rendra l'argument autodéterminé.
• Pour les fonctions qui utilisent plusieurs options de configuration dans les arguments, vous pouvez
  créer une classe (ou structure) distincte qui combine toutes les options. Et passer à fonctionner
  une instance de cette classe.
  Cette approche présente plusieurs avantages: les options sont indiquées par des noms, ce qui explique
  leur but. Le nombre d'arguments dans la fonction est réduit - le code est plus facile à écrire et à lire.
  Et si vous devez ajouter plus d'options, vous n'aurez pas à modifier l'appel de fonction lui-même.
  
• Au lieu d'expressions complexes dans les arguments, utilisez une variable intermédiaire à laquelle vous affectez une expression.
• En dernier recours, écrivez des commentaires à l'endroit de l'appel pour clarifier le but des arguments.

Considérez les exemples suivants:

 //    ? const DecimalNumber product = CalculateProduct(values, 7, false, nullptr); 

Essayons de peigner le code:

 ProductOptions options; options.set_precision_decimals(7); options.set_use_cache(ProductOptions::kDontUseCache); const DecimalNumber product = CalculateProduct(values, options, /*completion_callback=*/nullptr); 

Que ne pas faire

N'expliquez pas l'évidence. En particulier, il n'est pas nécessaire d'expliquer des choses qui sont évidentes pour une personne qui connaît le C ++. Au lieu de cela, vous pouvez décrire pourquoi ce code le fait (ou même rendre le code auto-descriptif).

Comparez:

 //    . <-- :  ! auto iter = std::find(v.begin(), v.end(), element); if (iter != v.end()) { Process(element); } 

Avec ceci:

 //  (Process) "element"     auto iter = std::find(v.begin(), v.end(), element); if (iter != v.end()) { Process(element); } 

Le code auto-descriptif ne nécessite aucun commentaire.
Le commentaire sur le code ci-dessus peut être généralement évident (et non nécessaire):

 if (!IsAlreadyProcessed(element)) { Process(element); } 

Ponctuation, orthographe et grammaire

Faites attention à la ponctuation, l'orthographe et la grammaire: il est beaucoup plus facile de lire des commentaires correctement écrits.

Les commentaires doivent être écrits comme une histoire: avec la disposition correcte des majuscules et des signes de ponctuation. Dans la plupart des cas, des phrases complètes sont plus faciles à comprendre que des fragments de phrases. Les commentaires courts, tels que ligne par ligne, peuvent être moins formels, mais devraient toujours suivre un style commun.

Bien que l'accent mis par le réviseur de code sur l'utilisation de virgules au lieu de points-virgules puisse être légèrement ennuyeux, il est important de maintenir un niveau élevé de lisibilité et de compréhensibilité. Une ponctuation, une orthographe et une grammaire appropriées y contribuent grandement.

Commentaires TODO

Utilisez les commentaires TODO pour un code temporaire ou une solution suffisamment bonne (intermédiaire, pas parfaite).

Le commentaire doit inclure la ligne TODO (toutes les majuscules), suivie du nom, de l'adresse e-mail, de l'ID du défaut ou d'autres informations pour identifier le développeur et la nature du problème pour lequel TODO est écrit. Le but de cette description est de pouvoir trouver plus de détails plus tard. TODO avec description ne signifie pas que le programmeur spécifié résoudra le problème. Par conséquent, lorsque vous créez TODO , le nom usuel est votre nom.

 // TODO(kl@gmail.com):  "*"  . // TODO(Zeke)   . // TODO(bug 12345):   " ". 

Si votre TODO ressemble à «Faisons-le différemment à l'avenir», indiquez soit une date spécifique («Corriger en novembre 2005») ou un événement («Supprimer ce code lorsque tous les clients traiteront les requêtes XML»).

Remarque:
- Les liens peuvent conduire à des sections du manuel qui n'ont pas encore été traduites.
- une discussion des questions générales est mieux faite dans la partie 1. Introduction