web-dev-qa-db-fra.com

Meilleure pratique pour les commentaires de fonction C ++

Existe-t-il une meilleure pratique acceptée pour commenter les fonctions? Je ne connais que le style doxygen mais il n'est pas officiellement supporté par C++ comme Javadocs est pour Java donc je me demande juste ce qui est le mieux.

c++coding-stylecomments
51
1337

Il n'y a qu'une chose générale avec laquelle la plupart des gens seront d'accord, c'est que les commentaires doivent dire "pourquoi", pas "quoi". En dehors de cela, les directives dépendent des normes de codage de votre lieu de travail.

Personnellement, je déteste le doxygène et autres, car cela contredit la première chose que j'ai dite. La "documentation", si on peut l'appeler ainsi, n'est qu'un fichier d'en-tête prédéfini. Et le coût? Code presque dupliqué, commentaires importuns (sérieusement, cela double la hauteur de tout) et juste une douleur.

Votre code doit être auto-documenté: utilisez des noms descriptifs, intégrez tout dans des tâches bien définies, etc. Les seuls commentaires doivent être des choses qui peuvent nécessiter des clarifications.

Par exemple, un extrait d'une classe de socket réseau que j'ai écrit:

const bool socket_connected(void) const;

Vous savez déjà ce que fait cette fonction; Je n'ai pas besoin de l'expliquer. Dois-je vraiment ajouter un gros morceau de commentaire expliquant qu'il retourne un booléen (duh) qui indiquera que le socket est connecté (duh)? Non. Doxygen va juste prendre mon en-tête et y ajouter une feuille de style sophistiquée.

Voici un exemple où une note rapide peut être utile (pour créer cette classe):

struct fancy_pants
{
    // doesn't transfer ownship, ensure foo stays alive
    fancy_pants(foo&);
};

Maintenant, il est clair que je dois m'assurer que le foo que je passe ne sort pas du cadre. Cela n'a pas nécessité l'uglification de mon code. Si je veux écrire de la documentation, je dois la rédiger, en décrivant la justification, l'utilisation prévue, les "gotcha", des exemples, etc. Comme Boost.

Cela dit, tous mes en-têtes ont un bloc de copyright en haut. Je trouve que c'est un endroit fantastique pour écrire un tout petit peu d'informations sur la classe. Par exemple, is_same.hpp:

/*-------------------------------------------------------
                    <copyright notice>

Determine if two types are the same. Example:

template <typename T, typename U>
void do_something(const T&, const U&, bool flag);

template <typename T, typename U>
void do_something(const T& t, const U& u)
{
    do_something(t, u, is_same<T,U>::value);
}

---------------------------------------------------------*/

Il donne une démo rapide en un coup d'œil. Quoi de plus, comme ce que j'ai dit ci-dessus, est dans un fichier de documentation écrite.

Mais vous voyez, je peux faire mes normes de code pour la plupart. Dans les entreprises, vous devez généralement suivre leur norme de toute façon.

47
GManNickG

Je m'en tenir aux balises de documentation Visual C++ MSDN recommande. Je vois MSDN comme la documentation officielle.

Exemple:

/// <summary>Sorts the list to by the given column</summary>
/// <param name="sel">Column to be sorted (index-1-based) and sort direction (pos. = ascending)</param>  
/// <returns>Documentation of return type</returns>  
void CExamlist::SetSorting(int sel) { ... }

Obtient interprété par ReSharper C++ pour

enter image description here

Visual Studio 2012+ interprétera également ces commentaires en fonction de Comment écrire des commentaires C++ qui apparaissent dans Intellisense?

CppTripleSlash est un excellent plugin VS gratuit qui ajoute les bonnes balises XML après avoir tapé "///". Cette fonctionnalité est portée à partir de l'éditeur C # de Visual Studio.

6
OneWorld

Rien ne sera "officiellement" pris en charge car il n'y a pas d'entreprise derrière C++.

Comme vous pouvez le voir, doxygen prend en charge de nombreux blocs différents http://www.doxygen.nl/docblocks.html

Personnellement, je préfère rester proche des autres recommandations. J'essaie de rester proche des meilleures pratiques javadoc.

6
X-Blaster

Vous pouvez suivre le Google Style pour commenter.

Types de choses à mentionner dans les commentaires lors de la déclaration de fonction:

  • Quelles sont les entrées et sorties.
  • Pour les fonctions membres de classe: si l'objet se souvient des arguments de référence au-delà de la durée de l'appel de méthode, et s'il les libérera ou non.
  • Si la fonction alloue de la mémoire que l'appelant doit libérer.

  • Indique si l'un des arguments peut être NULL.

  • S'il y a des implications de performance sur la façon dont une fonction est utilisée.

  • Si la fonction est réentrante. Quelles sont ses hypothèses de synchronisation?

6
codaddict

Outre Google Standards, j'ai trouvé ce guide ici par Edward Parrish très utile!

Par exemple, les commentaires de bloc:

/**
    CS-11 Asn 2
    checks.cpp
    Purpose: Calculates the total of 6 checks

    @author Ed Parrish
    @version 1.1 4/10/16 
*/

ou commentaires de code de fonction:

/**
    Encodes a single digit of a POSTNET "A" bar code.

    @param digit the single digit to encode.
    @return a bar code of the digit using "|" as the long
    bar and "," as the half bar.
*/

Son moins verbeux que le doxygène et le maintient minimal. Vous pouvez consulter le lien pour plus de détails.

2
BugShotGG

Je pense que le "meilleur" style n'existe pas. Vous devez utiliser celui qui vous convient. Il varie fortement en fonction de l'objectif du code. Les API de bibliothèque publique ont le plus besoin de ces commentaires. D'un autre côté, les méthodes privées de classes d'implémentation peuvent probablement s'appuyer uniquement sur l'auto-documentation, car aucun commentaire n'est généralement meilleur que les commentaires erronés/obsolètes.

Soit dit en passant, Doxygen prend en charge plusieurs styles, Javadoc étant l'un d'entre eux.

2
Alex Jenter

Il existe un certain nombre de conseils pour commenter, à tel point qu'il contient un chapitre entier dans Code Complete . Veuillez noter que les styles Javadocs et Doxygen répondent également à la génération automatique de documentation. Ce qu'ils ont encouragé est généralement bien.

Voici quelques conseils que je trouve importants:

  1. Les commentaires doivent décrire pourquoi, pas ce que vous faites

  2. Les commentaires doivent être sous une forme facile à maintenir et à taper. Pas d'en-tête et d'art ascii fantaisistes s'il vous plaît!

2
Extrakun