Existe-t-il des formats standards pour les commentaires dans le code?

Je me demande si les gens ont un format standard pour les commentaires dans le code. Pas les choses comme les commentaires xml pour une méthode ou une classe, mais plutôt des commentaires dans une méthode.

Voir aussi:

Est-il un standard (comme phpdoc ou python docstring) pour les commentaires de code C#?

source d'informationauteur daustin

comments

22

Vous devriez vraiment envisager un couple de choses à faire de bons commentaires au-delà de la mise en forme.
1. Ne pas simplement répéter ce que fait le code. Par exemple,
```
 //Start the services
 StartServices();
```
est une branlant terrible commentaire!
1. Décrire pourquoi. Pourquoi est-ce que le code fait ce qu'il fait? Quelle est la prise en charge ou de l'algorithme de l'étape?
2. Format de vos commentaires pour un maximum de lisibilité. Onglet correctement, laisser des espaces si nécessaire, etc.
3. Si quelqu'un a déjà commencé à commenter dans un façon standard, ne se cassent pas la norme.
4. Vérifier cet article sur MSDN sur l'écriture efficace commentaire: http://msdn.microsoft.com/en-us/library/aa164797.aspx
6
```
//I usually write comments like this
```
Où je travaille, il est nécessaire d'utiliser la norme xml de commentaires du style pour la plupart des déclarations (des classes, des méthodes, des propriétés) (nous utilisons C#).

Parfois, vous pouvez voir l'en-tête/pied de page de commentaires en cours d'utilisation.
```
/****************************************************/
//Filename: Customer.cpp
//Created: John Doe
//Change history:
//18.12.2008 /John Doe
//14.01.2009 /Sara Smith
/****************************************************/

/* Here goes a lot of stuff */

/****************************************************/
//EOF: Customer.cpp
/****************************************************/
```
Quelque chose de ce genre a été utilisé lors d'un de mes anciens lieux de travail. À mon avis, trop de trucs inutiles. Changer l'histoire est très bien vu ces jours-ci par le biais d'un système de contrôle de version.

À bon logiciel de magasins il y a des lignes directrices internes pour le moment et la façon d'écrire des commentaires. Les Documents sont généralement dénommé "code Source de style politique" ou de quelque chose. Il est très important de respecter un style commun de commenter le code.

Bien sûr, ce commentant hype ne devrait pas aller trop loin que de faire des commentaires chaque petit morceau de code, en particulier les plus évidents.
```
///<summary>
///    Handles the standard PageLoad event
///</summary>
///<param name="sender">
///   Event sender
///</param>
///<param name="e">
///   Event arguments
///</param>
public void Page_Load (object sender, EventArgs e)
{
    //Do something here
}
```
Celui-ci est un bon exemple de la sur-l'obsession de la commenter. Quelque chose comme ceci ajoute exactement zéro de l'information, mais seulement ajoute du bruit à la source de fichier. Et nous devons le faire au travail, à la demande.

Mon opinion personnelle, c'est d'ajouter des commentaires quand vous avez quelque chose à dire ou expliquer, pas juste pour le plaisir de commenter le tout.
4

Commentaire sur la ligne au-dessus du code (bloc) qui fait ce que vous décrivez
```
//This is a comment.
Some code goes here
```
Éviter de faire des trucs comme
```
//----------------
//IMPORTANT COMMENT
//----------------
```
Et je ne peux pas utiliser le
```
/* comment */
```
Et peut-être plus important encore, de nettoyer les commentaires! Un commentaire qui décrit inexistante fonctionnalité est pire que pas de commentaire.

/**
 * block comments to document a method for javadoc go like this
 * @param
 * @return
 * @exception BTKException
 * @see BTK
 */

3

Je ne peux pas croire que nous avons raté le REM mot-clé.

Mais pour être juste, c'est pour la REMARQUE fait pas de COMMENTAIRE.

//For one line, I write them like this

/*
For multiple lines of text
I write them like this
*/

/*
for(multiple lines of code){
  I.WriteComents(With("//"));
  Reason==If(I.Remove('The top begin-quote mark') then
    I.Worry.Not('About removing the close-quote mark');
//*/

3

Le problème avec les commentaires à l'intérieur d'une méthode (plutôt que dans une interface), c'est qu'ils ne sont pas destinés à être vus par n'importe qui, sauf pour les gens du maintien de cette méthode. Par conséquent, il n'y a pas de réel besoin d'une norme pour les commentaires. Ils ne sont pas publiés n'importe où, ils ne sont pas visibles par le public, les appelants généralement de ne jamais les voir.

En général, les commentaires à l'intérieur de code doit respecter quatre règles:
1. Ils ne devraient pas l'évidence
2. Elles doivent être cohérentes avec ce qu'ils décrivent
3. Il devrait être clair ce ils décrivent (p. ex., ligne, un bloc).
4. Ils devraient être lisibles par n'importe quel avenir responsable.
Cela étant dit, il y a souvent une tendance à la place de l'information qui est importante pour les appelants comme un commentaire interne. Par exemple: "OUPS, Ce ne gère pas les nombres négatifs". Chaque fois que vous voyez un commentaire interne, de réexaminer si l'en-tête de la documentation doit être mise à jour ou utiliser un outil qui "pousse" les commentaires à la prise de conscience de la fonction appelants (J'ai un outil comme ça pour Java).

/* I will sometimes write
comments like this */

# ----------------------------------
# BIG IMPORTANT COMMENTS IN PERL/SH
# ----------------------------------

1
```
' I usually write comments like this
```
1
```

```

//Cheap Debugger

//Response.Write(MySQLStringBecauseINeedToKnowWhatsBroken);

1

Commentaires les normes sont plus utiles lorsque le commentaire sera analysé par un outil externe (en général, un document générateur, comme javadoc).

Dans ce cas, l'outil externe précise les normes.

Pour d'autres cas, voir Comment aimez-vous vos commentaires? (Meilleures Pratiques)
0
```
(* Modula-2 comments go like this *)
```
0

Si vous êtes paranoïaque et ne pas l'utiliser ou de la fiducie de contrôle à la source, vous pourriez faire ceci
```
//Initials-YYMMDD-fixNo-Start
dosomething();
//Initials-YYMMDD-fixNo-Finish
```
Il fait un putain de bordel, mais il vous donne une certaine façon à l'annulation des modifications.

Mais je suggère de l'aide de la source de contrôle
0

Il peut y avoir des guerres de religion sur ce sujet.

Ce que j'essaie de faire, qui ne cause pas trop de guerre, est
```
 //explain the purpose of the following statement in functional terms
... some statement ...
```
L'idée est, si j'exécute le code à travers un programme qui supprime tout sauf les commentaires, ce qui est à gauche est assez bon en pseudo-code.

Quelque chose d'utile comme un moyen de commenter le code que vous pensez que vous pourriez avoir besoin est:
```
 /*
 ... some code ...
/**/
```
puis modifiez la première ligne, soit les supprimer, les modifier ou de les /**/
```
 /**/
... some code ...
/**/
```
0
```
/*
 * Brief summary of what's going on.
 */
int code_that_goes_on(int c)
{
     /* and then if I have to remark on something inside... */
     return 0;
}
```
99% des compilateurs de soutien // commentaires, ce qui est génial, mais que 1% existe toujours, et il n'est pas trop difficile de rendre la vie vivable pour eux.

EDIT: Delphi commentaire est un peu obtus, mais n'est point une véritable carence. J'ai l'intention d'en faire un C-réponse spécifique.
0

J'aime faire des choses comme ceci:
```
/************
*  Comment  *
************/
```
Cette façon, j'ai à perdre du temps à reformater l'ensemble du bloc tout le temps-je ajouter/supprimer du texte
0

Je ne pense pas qu'il y est une norme pour ce que vous demandez. Et je ne vois pas comment il allait ajouter quelque avantage de ///des commentaires sur la méthode elle-même.

Pour la création de documents à partir de vos classes C# de prendre un coup d'oeil à Château de sable.
0

En C/C++/C#/Java, quand j'ai un commentaire expliquant un bloc de code:
```
//comment
code;
more_code;
```
lorsqu'un commentaire est en train d'expliquer une seule ligne:
```
code; //comment
```
J'ai l'habitude d'utiliser // pour seule phrase commentaires et /* ... */ commentaires pour le multi-phrase commentaires.

Un style de commentaires en C++/Java, etc est-ce:

//Use //for all normal comments...
//and use multiline comments to comment out blocks of code while debugging:
/*
for(int i = 0; i < n; ++i) {
    //If we only use //style comments in here,
    //no comment here will mess up the block comment.
}
*/

Je pense que c'est un point intéressant, même si il n'est pas très utile.

0

Mon code est auto-documentation. Je n'ai pas besoin de commentaires.
0

Il existe des logiciels qui peuvent vous aider à rédiger et le format de la documentation. Ils nécessitent quelques modifications spécifiques afin qu'ils puissent identifier les classes de commentaires.

comme doxygen:

http://www.stack.nl/~dimitri/doxygen/docblocks.html
```
/*! \brief Brief description.
 *         Brief description continued.
 *
 *  Detailed description starts here.
 */
```
0

Je suis surpris de voir que pas plus de personnes recommandé doxygen. C'est une bonne façon de documenter le code, les effets secondaires, il peut automatiquement générer du html + pdf de la documentation de l'API à la fin de la journée.

Je préfère les commentaires de cette manière pour la fonction

/**
 * Activates user if not already activated
 * @param POST string verificationCode
 * @param POST string key
 * @return true on success, false on failure
 * @author RN Kushwaha <[email protected]>
 * @since v1.0 <date: 10th June 2015>
 */

fonction publique activateUserAccount() {

//du code ici

}

Je utiliser une seule ligne de commentaire pour les descriptions de code comme

//check if verificationCode exists in any row of user table
code here

-1

-- J'ai l'habitude d'écrire des commentaires de ce genre

dans SQL

Vous devez vous connecter pour publier un commentaire.