Meilleures pratiques: Où les commentaires de fonction devraient-ils aller dans le code C / C ++?

Donc... je comprends que cela peut être subjectif, mais j'aimerais avoir quelques avis sur ce que les meilleures pratiques pour ce qui est.

Dire que j'ai l'en-tête suivant et .fichier cpp:

en-tête:

//foo.h

class foo
{
public:
    int bar(int in);
};

rpc:

//foo.cpp

int foo::bar(int in)
{
    //some algorithm here which modifies in and returns the modified value
}

Maintenant dire que j'ai cette fonction commentaire:

/* 
    input:    an integer as input to algorithm foo

    output:   The result of the algorithm foo on input in

    remarks:  This function solves P = NP
*/

Serait la meilleure pratique est de faire de cette fonction un commentaire dans l'en-tête au-dessus de la déclaration de la fonction ou au-dessus de la définition de la fonction dans le fichier cpp? Merci

source d'informationauteur Polaris878

  1. 46

    J'ai mis des commentaires décrivant ce la fonction dans l'en-tête et des commentaires décrivant comment il le fait dans le fichier cpp.

  2. 9

    J'ai tendance à utiliser doxygen du format en fonction des commentaires dans le fichier d'en-tête, permettant aux programmeurs qui coup d'oeil dans pour en savoir plus.

    /**
 * Fills the handler with GIF information
 * 
 * @param filename GIF File name to be loaded
 * @return Inited GIF Handler or NULL for error
 */
pGifHandler gifHandlerLoad(const char* filename);

/**
 * Removes all data used by the GIF handler
 * 
 * @param gifHandler GIF Handler to be destroyed
 * @note This also clears palette and bitmap(s)
 */
void gifHandlerDestroy(pGifHandler gifHandler);

    Programmeurs qui veut savoir comment une certaine fonction-t-il de l'emploi, devrait coup d'oeil dans le .cpp fichier qui serait commenté sur la façon dont il atteint le but.

  3. 5

    Dans l'ordre d'importance:

    1. Si elle fait partie d'un projet existant, et il est en vigueur style de commentaires, utilisez-le. La cohérence au sein d'une base de code est plus important que développeur de préférence.

    2. Si c'est un nouveau projet, utiliser Doxygen ou similaire à la documentation de votre code. Bien que cela ne répond pas à votre question, puisque vous pouvez utiliser les deux styles. Exécuter tous les soirs, de sorte que vous avez à jour consultable source de documentation.

    3. Personnellement, je préfère ne mettre qu'bref résumé d'une ligne d'en-ligne des fonctions et des membres dans les fichiers d'en-tête, car il rend plus difficile d'obtenir un bref aperçu des fonctionnalités de classe lors de l'écrémage par le fichier d'en-tête. La description détaillée je pars pour le .fichier cpp. Certains accesseurs je n'ai pas de commentaire si leur but est vraiment évident.

    J'ai aussi une grosse bête noire sur paresseux commentaires, en particulier des one-liners:

    par exemple, Ce commentaire est un gaspillage de l'espace et peut ainsi être supprimés:

    /** Get the width */
double getWidth();

    Ce commentaire est utile:

    /** Get the width in inches excluding any margin. */
double getWidth();
  4. 3

    De placer des commentaires dans l'en-tête est une meilleure solution. C'est parce que:

    • Lors de la recherche de la documentation sur
      une fonction, la tête est la première
      endroit à vérifier.
    • Le fichier source peut ne pas être disponible.
    • Le fichier source contient beaucoup plus de
      que la déclaration de la fonction, et la
      observations utiles peuvent obtenir noyé.
  5. 3

    - Je utiliser Doxygen et l'utilisation d'une courte ligne la description de l'en-tête et un costaud multi-description des lignes dans le fichier d'implémentation. Je pense que cela donne nettoyeur de fichiers d'en-tête qui sont plus faciles sur les yeux.

    Remarque: Si vous avez été la publication de ce code comme une bibliothèque, les gens pourraient ne pas vouloir creuser dans la mise en œuvre. Cependant, les fichiers d'en-tête sont généralement juste jeu. Dans ce cas, je mettrais une documentation détaillée dans l'en-tête.

    en-tête:

    //foo.h

class foo
{
public:
    /**\brief This function solves P = NP */
    int bar(int in);
};

    rpc:

    //foo.cpp

/** 
 \param[in]    an integer as input to algorithm foo

 \returns    The result of the algorithm foo on input in
*/
int foo::bar(int in)
{
    //some algorithm here which modifies in and returns the modified value
}
  6. 3

    Personnellement, je préfère le mettre au-dessus de la mise en œuvre. Je voudrais aussi utiliser Doxygen style, car il donne la même info, mais permet de générer la documentation.

    Il n'a pas vraiment d'importance, surtout si vous allez construire séparée de la documentation avec doxygen. Aller avec ce que VOUS préférez.

  7. 2

    Fonction de la placer des commentaires dans le fichier d'en-tête. Que (hormis le manuel) est le premier endroit où les utilisateurs de votre classe va chercher de la documentation. Ils ne se soucient pas de la mise en œuvre, juste au sujet de l'interface.

  8. 2

    J'aime utiliser des PRÉ /POST-conditions. Aucune de ces réponses sont fausses.
    Que pouvez-vous /la société préférez. Mais les PRÉ et POST conditions vous dire quels sont les appels entrants /sortants variables et comment ils sont utilisés. Il s'assure également que vous suivez une sorte de ligne directrice sur la façon dont vous allez appeler la fonction (pré-requis) et quels sont les résu après cette fonction (post-conditions).

  9. 2

    En général, les commentaires devraient être traitées de manière similaire à la séparation de code -- interfacecommentaires (comme dans votre exemple) permettrait d'aller dans l'en-tête, tandis que mise en œuvre-commentaires connexes serait mieux adaptée pour la .fichier cpp.

    Si quelqu'un devait inclure vos classes dans leurs propres programmes, ils devraient être en mesure d'obtenir suffisamment d'informations dans le fichier d'en-tête pour savoir comment utiliser la classe sans avoir à casser dans la mise en œuvre elle-même. Commentaires d'en-tête, supérieures à celles qui sont probablement inutiles et ne servent qu'à encombrer les informations utiles.

  10. 2

    C'est comme demander à ce que les meilleures pratiques pour mettre vos chaussettes est. Certains outils ont une meilleure chance de travailler si vous mettez de la déclaration et de commenter ensemble, et que le fait probablement le plus de sens à ce que les gens attendent. Mais en commentant de façon aléatoire est inutile. Avoir in/out des trucs en particulier, sauf si vous avez un outil qui utilise. N'importe quel programmeur peut voir ce qu'il ou elle a besoin à partir de la déclaration, et la même chose s'applique à la langue en général. Rien n'est plus inutile que de tels commentaires //c'est le constructeur.

    Plutôt essayer de garder le code en lui-même aussi simple que possible avec les noms qui ont un sens et une organisation générale du code et si il n'y a rien d'étrange à écrire tout un chapitre à ce sujet comme
    //Nous avons eu à le faire car un peu bizarre de l'api que nous utilisons implique certaines choses
    //qui a causé quelques autres choses pour les casser et les appels à optimiser parfois
    //il ne faut pas prendre ces appels de méthode ou de l'optimizer optimise out
    //quelques autres trucs et tout le programme cesse de fonctionner

  11. 1

    La meilleure pratique est quelle que soit la norme de l'organisation pour laquelle le code est écrit.

    Si c'est juste pour moi:

    De la fonction objectif et l'utilisation dans l'en-tête, les détails de la fonction dans la mise en œuvre.

  12. 1

    Parce que j'ai toujours utilisé Visual Assist X, et ont la capacité de sauter autour de code très facilement, j'utilise le fichier d'en-tête comme un indice. Qui est, le fichier d'en-tête contient uniquement les données pertinentes, sans ajout de commentaires que de ne pas ajouter de ballonnement dans le fichier. Si le lecteur veut de plus amples informations sur la fonction qu'ils peuvent sauter à la rpc.

    Cela suppose bien sûr que toutes les personnes qui lisent votre code aura le même processus de pensée, ce qui est faux. Il est agréable d'avoir seulement la météorisation dans un seul fichier.

  13. 1

    But dans l'en-tête de contrat, fonction ci-dessus implementaiton, pourquoi dans le corps de la fonction.

    Qui nécessite soit les délivrer .rpc, ou d'utiliser un outil comme doxygen de publier la documentation.

    Avantage lors de dépendances: l'amélioration de la documentation n'affectera pas d'en-tête de dépendances.

    De toute façon, choisir un style, et être cohérent

  14. 1

    L'intérieur de la fonction, vous pouvez mettre le commentaire sur la même ligne que l'accolade d'ouverture.

    
/* what is this function for, and so on.  Stuff the caller needs to know. */
foo ()
{       //pre-condition
}

    J'ai vu que recommandé comme un emplacement pour l'inscription de pré-conditions. J'ai essayé, et constaté qu'il est assez à l'étroit, parce que j'ai tendance à écrire des commentaires verbeux. Aussi, la pré-condition est quelque chose de l'appelant doit être au courant, et il ne devrait pas se perdre à l'intérieur du corps de la fonction.

    Sinon, j'ai toujours essayer de mettre ensemble les descriptions de la fonction à l'extérieur, et des explications de pourquoi il est codé de la façon dont il est à l'intérieur de la fonction, à côté du code. Donc en général d'accord avec le Doxygen des promoteurs de style.