Quels sont les exemples de commentaires qui vous disent pourquoi au lieu de comment ou quoi? [fermé]

Tout d'abord, dans cette question, je voudrais rester à l'écart de la polémique sur la question de savoir si les commentaires sur le code source sont bons ou mauvais. J'essaie simplement de comprendre plus clairement ce que les gens veulent dire quand ils parlent de commentaires qui vous disent POURQUOI, QUOI ou COMMENT.

Nous voyons souvent des directives telles que "Les commentaires devraient vous dire POURQUOI; le code lui-même devrait vous dire COMMENT". Il est facile d’accepter l’affirmation à un niveau abstrait. Cependant, les gens laissent généralement tomber cela comme un dogme et quittent la pièce sans autre explication. J'ai vu cela utilisé dans tellement d'endroits et de contextes différents, qu'il semble que les gens puissent s'entendre sur le slogan, mais ils semblent parler de choses complètement différentes.

Revenons donc à la question: si les commentaires vous disent POURQUOI, de quoi s'agit-il, POURQUOI? Est-ce la raison pour laquelle ce morceau de code existe en premier lieu? Est-ce ce que ce code pièce devrait faire? J'apprécierais vraiment si quelqu'un pouvait donner une explication claire, puis ajouter quelques bons exemples (les mauvais exemples ne sont pas vraiment nécessaires, mais je ne peux pas les ajouter pour contraster).

Il y a beaucoup de questions sur le fait de savoir si les commentaires sont bons ou mauvais, mais personne ne répond à la question spécifique de savoir quels sont les bons exemples de commentaires qui vous disent POURQUOI.

L'exemple le plus courant et le plus distinctif concerne les commentaires sur diverses solutions de contournement. Par exemple celui-ci:

https://github.com/git/git/blob/master/compat/fopen.c :

/*
 *  The order of the following two lines is important.
 *
 *  FREAD_READS_DIRECTORIES is undefined before including git-compat-util.h
 *  to avoid the redefinition of fopen within git-compat-util.h. This is
 *  necessary since fopen is a macro on some platforms which may be set
 *  based on compiler options. For example, on AIX fopen is set to fopen64
 *  when _LARGE_FILES is defined. The previous technique of merely undefining
 *  fopen after including git-compat-util.h is inadequate in this case.
 */
#undef FREAD_READS_DIRECTORIES
#include "../git-compat-util.h"

Vous trouverez sûrement plus d'exemples dans les sources Git et Linux; les deux projets essaient de suivre cette règle.

Je recommande également de suivre cette règle encore plus strictement avec les logs de commit . Pour les commentaires de code, il peut arriver que vous corrigiez le code, mais oubliez de mettre à jour le commentaire. Avec la quantité de code dans le projet habituel, il est garanti que cela arrivera tôt ou tard. D'autre part, le journal de validation est lié au changement particulier et peut être rappelé à l'aide de la fonctionnalité "annoter" / "accuser" du système de contrôle de version. Encore une fois, Git et Linux ont de bons exemples.

Regardez par exemple ce commit . (ne pas copier ici, c'est trop long). Il comporte quatre paragraphes qui prennent une page presque entière (et un peu trop d’écran) décrivant ce qui était faux exactement et pourquoi c’était faux, puis continue et modifie toutes les SIX lignes. Ils utilisent des commentaires comme celui-ci à deux fins:

1. Toutes les modifications soumises sont examinées et le journal de validation est ce qui doit expliquer la modification à l'examinateur.
2. Lorsqu'un bogue est trouvé, les journaux pertinents sont récupérés en utilisant "pickaxe" ou "blame" pour éviter de revenir à un comportement antérieur incorrect également.

(note: il m'a fallu au plus 10 minutes de navigation aléatoire dans le dépôt git pour arriver à ces deux exemples, il serait donc facile d'en trouver plus ici)

Un commentaire qui explique pourquoi explique le raisonnement derrière le code - par exemple:

// We need to sync the values if the temp <doodad> GUID matches one of the active <doodad>'s
// GUID, as the temp <doodad> has the most recent values according to the server and said 
// values might have changed since we added the <doodad>. We want a user to be able to <foo> 
// the <doodad> whenever, which means those values must be accurate.
for (doodad in doodads) {
    if ([doodad guid] == [tempDoodad guid]) {
        [doodad updateFromDoodad:tempDoodad];
        break;
    }
}

Un commentaire qui vous explique comment explique ce que fait le code.

// Loop through our <doodads> and check for a GUID match. If it matches, copy the new values
// on the <doodad> that matches 
for (doodad in doodads) {
    if ([doodad guid] == [tempDoodad guid]) {
        [doodad updateFromDoodad:tempDoodad];
        break;
    }
}

La différence est qu'un responsable peut regarder le premier et dire: "Oh, alors c'est peut-être obsolète!" Dans le second cas, ledit responsable a un commentaire qui ne dit rien du code lui-même ne révèle pas (en supposant que les noms de variables sont corrects).

Voici un exemple concret de pourquoi, à partir d'un code iOS sur lequel j'ai travaillé pour obtenir une adresse de passerelle (ou une estimation raisonnable pour celle-ci). J'aurais pu laisser les commentaires qui disaient des choses comme "Initialiser la prise de réception", mais cela ne ferait que dire à un responsable (ou à moi futur) ce qui se passait, pas à la raison pour laquelle je devais faire cet étrange kludge pour obtenir l'adresse de la passerelle dans le répertoire. première place.

/*
 We're going to do something really hacky here and use a custom partial
 implementation of traceroute to get our gateway IP address.

 [rant removed - irrelevant to the point]

 There's no good way to get at the gateway address of an iDevice
 right now. So, we have two options (per https://devforums.apple.com/message/644915#644915 ):
 1. Get at and parse the routing table (like netstat -rn, or route -n)
 2. Do a traceroute and grab the IP address for the first hop

 As far as I can tell, the former requires <sys/route.h> from the Mac OS X
 header files, which doesn't seem like a good idea to me. Also, there's a
 thread on the Apple Developer forums that seems to imply that header isn't
 in iOS for a reason (https://devforums.apple.com/message/774731#774731 ).

 So when we send our request with a TTL of one it will survive a single hop
 to the router and return, triumphant, with the router's IP address!

 Viva la kludge!

 PS: Original source was the below SO question, but I've modded it since then.
 http://stackoverflow.com/questions/14304581/hops-tracing-ttl-reciveform-on-ios/14304923#14304923
 */

// Default to using Google's DNS address. We used to try checking www.google.com
// if reachability reported we had internet, but that could still hang on routers
// that had no internet connectivity - not sure why.
const char *ip_addr = [kGoogleDNS UTF8String]; // Must be const to avoid undefined behavior
struct sockaddr_in destination,fromAddr;
int recv_sock;
int send_sock;

// ... more code follows

Je voudrais commencer ma réponse par une citation de Jeff Atwood dans son article de blog Code vous dit comment, des commentaires vous expliquent pourquoi :

les meilleurs commentaires sont ceux dont vous n'avez pas besoin

Il déclare également que:

Vous devez d’abord vous efforcer de rendre votre code aussi simple que possible à comprendre sans compter sur les commentaires comme une béquille. Si vous ne parvenez pas à ajouter des commentaires, vous ne pourrez pas comprendre plus facilement le code.

Je suis tout à fait d’accord et à ce stade, je dois ajouter qu’avant de pouvoir commencer à rendre le code aussi simple que possible, je le fais fonctionner puis je commence à le refactoriser. Ainsi, lors de la première exécution avant la refactorisation, il est très utile d’ ajouter pourquoi les commentaires .

Par exemple, si vous utilisez 3 boucles imbriquées avec des tables de hachage bidimensionnelles pour remplir un tableau des jours de la semaine tout en analysant les données, il est très facile de perdre le fil de ce qui a été fait par quelqu'un ou même par vous-même si vous ne le regardez pas pendant quelques semaines et que vous le refactuez subitement.

[loop1]6oclock -> [loop2]Monday -> [loop3]stage 1 to 4
         -> tuesday-> stage 1 to 4
         ...
         -> Saturday -> stage 1 to 4
    7oclock -> Monday-> stage 1 to 4
        ....etc.

La partie supérieure est un exemple de la façon dont 3 boucles imbriquées fonctionneraient avant la refactorisation.
Expliquer également certaines conditions de branche peut aider à comprendre le code beaucoup mieux avec ce que l’on pensait au cours du processus:

// added a zero before the actual day in order for the days always to be 2 digits long.
if( actualDayFuture < 10 ) 
{ 
     actualDayFuture = padIfSingleDigitDate(actualDayFuture); 
}

Même un code simple et évident fonctionne bien avec des commentaires. Juste pour rendre les choses un peu plus évidentes, plus claires ou plus faciles à comprendre pour vos collègues et même pour vous-même lors de la maintenance de logiciels.

Certes, xp dit que le code s’explique de lui-même, mais un commentaire d’une ligne fait-il mal?

Je trouve également les règles suivantes de ce blog très utiles:

• Comprendre le matériel avant d'écrire
• Ecrivez comme si votre public était une quatrième niveleuse
• Pensez à la façon dont les lecteurs pourraient mal interpréter

Quiconque doit réintégrer son propre code ou quelqu'un d'autre ou même du code hérité sait que cela peut être un casse-tête. Donc, au lieu d’être paresseux ou d’essayer d’être un super codeur en ne commentant rien du tout ou très peu, pourquoi ne pas créer votre propre ou celui d’un pauvre pauvre, qui doit maintenir votre code, la vie future beaucoup plus facilement en suivant les règles citées.

De nombreuses décisions de programmation sont douteuses lors des révisions et la raison pour laquelle certaines parties ont été écrites n'est pas toujours claire, même si certaines sections de code sont vitales pour qu'un programme fonctionne, en raison d'un bogue majeur détecté car le code a été utilisé pendant des années. . Donc, pour ne pas vous ennuyer complètement avec un tl; dr avec une dernière citation d’ acmqueue :

Une documentation préalable, claire et complète est un élément clé de la création d'un logiciel capable de survivre et de s'adapter. La documentation conforme à des normes élevées réduira le temps de développement, améliorera le travail et améliorera les résultats. Il est difficile de demander plus que cela, peu importe la technique.

J'ai tendance à réduire les commentaires à des références où une certaine fonctionnalité / code est expliquée plus en détail ou à expliquer pourquoi un certain mode de programmation est choisi.

Etant donné que d’autres programmeurs ayant des compétences similaires utilisent ou lisent votre code, il est important de faire un commentaire si vous utilisez une méthode différente de celle attendue. Vous pouvez donc expliquer dans un commentaire pourquoi vous avez choisi cette méthode.

Par exemple, si vous pouvez utiliser deux capteurs différents sur un appareil Android et que l’un ne correspond pas à vos besoins, vous pouvez expliquer dans le commentaire pourquoi vous avez choisi l’autre.

Le «pourquoi» devrait donc justifier vos choix.

Les commentaires devraient vous dire ce que le code ne dit pas, pas nécessairement délimité par WHY , HOW ou WHAT . Si vous avez de bons noms et des fonctions bien délimitées, il est fort possible que le code puisse vous dire exactement ce qui se passe. Par exemple:

List<LightMap> maps = makeLightmaps(receivingModels);
TrianglePartitioner partition = new Octree(castingTriangles);
List<Photon> photons = firePhotons(lights, partition);

if (photons.Count > 0)
{
      PhotonPartitioner photonMap = new KDTree(photons);
      gatherPhotons(maps, photonMap, partition, lights);
}

Ce code n'a vraiment pas besoin de commentaires. Les noms de fonction et de type facilitent la compréhension.

Parfois, cependant, il peut être difficile voire impossible de créer un code fluide comme ci-dessus. Par exemple, l'extrait de code suivant sert à trouver un point statistique sur une sphère. Les maths sont assez opaques, donc un commentaire avec un lien vers l'explication est utile pour aider à dire COMMENT ça marche. Cela peut être encapsulé dans une fonction pour dire CE qu’il fait sans avoir besoin de commentaire si besoin plus d’une fois, sinon le titre du lien est également utile dans ce département.

double randomA = localGenerator.NextDouble();
double randomB = localGenerator.NextDouble();

//http://mathworld.wolfram.com/SpherePointPicking.html
double theta = 2 * Math.PI * randomA;
double phi = Math.Acos(2 * randomB - 1);

Vector3 randomDirection = new Vector3(Settings.ambientRayLength * (float)(Math.Cos(theta) * Math.Sin(phi)),
                                      Settings.ambientRayLength * (float)(Math.Sin(theta) * Math.Sin(phi)),
                                      Settings.ambientRayLength * (float)Math.Cos(phi));

Un autre exemple de commentaire dans lequel les commentaires vous disent ce que le code ne permet pas est d’expliquer une décision. Dans l'exemple suivant, le code ne verrouille pas une variable non locale à un thread à l'intérieur d'un morceau de code threadé. Il y a une raison à cela et le commentaire explique POURQUOI . Sans le commentaire, cela pourrait être considéré comme un bug, ou simplement ne pas être remarqué.

Random random = new Random();
Parallel.For(0, maxPhotons, delegate(int photonIndex, ParallelLoopState state)
{
    ...
    //I don't actually care if this random number is unique between threads, threadsafty is not that big of a deal
    //  in this case and locking the random object could cause a lot of lock contention
    while (random.NextDouble() > reflectProbability)
    {
        ...
    }
    ...
}

Peut-être pourrait-on améliorer la raison pour laquelle l'objet aléatoire n'est pas créé à l'intérieur de la boucle parallèle en premier lieu. S'il n'y a pas de raison, cela pourrait aussi amener quelqu'un à venir et à se rendre compte que l'idée est stupide et constitue un bon endroit pour refactoriser.

Il peut être utile de reconnaître différents types de "pourquoi", notamment:

• Les raisons pour lesquelles un code qui semble trop complexe ne fonctionneraient pas si elles étaient simplifiées (par exemple, une conversion de type apparemment superflue peut être nécessaire pour garantir que le code fonctionne dans certains cas critiques).

• Les raisons pour lesquelles une opération simple et apparemment dangereuse est réellement sûre (par exemple, "notre routine d'extraction de données rapportera un élément factice passé comme dernier élément, comme étant inférieur à tout le reste, et l'élément suivant comme étant supérieur; tout élément devant être trié avant un autre, dans une séquence constante ascendante ou descendante, sera suivi par au moins un élément supplémentaire (éventuellement factice) ").

Dans de nombreux cas, un commentaire du second type dans une partie du code peut "correspondre" à un commentaire du premier type dans une autre (par exemple, "Bien qu'il semble que cette séquence d'opérations puisse être simplifiée, la routine Fitz repose sur le Wongle n’est pas Woozled tant que le Bandersnatch n’a pas été blanchi. ")

N'oubliez pas que si vous écrivez un programme, vous ne faites pas que taper des choses au hasard, vous le faites parce que vous avez un modèle de ce que vous voulez , que ce soit dans un document officiel ou dans votre tête. Les choses dans votre tête sont aussi réelles que les logiciels / données d'un ordinateur (et tout aussi susceptibles de contenir des bugs).

Quelqu'un lisant votre code peut ne pas avoir ce modèle en tête, aussi les commentaires peuvent-ils servir à leur dire quel était le modèle et comment le code s'y rapporte. Je pense que c'est ce que l'on entend par "pourquoi". Certes, il est bon de rendre le code lui-même aussi explicite que possible, mais cela ne suffit pas toujours. Exemple:

// transform the x,y point location to the nearest hexagonal cell location
ix1 = (int)floor(0.5 + x + y/2);
iy1 = (int)floor(0.5 + y);

En plus de cela, le modèle change avec le temps et ces modifications doivent être transférées dans le code. Les commentaires doivent donc non seulement indiquer «pourquoi», mais aussi comment le modifier en fonction des modifications prévues du modèle. Exemple:

// to change to square cell locations, remove the "+ y/2" in the above code

Je pense que le but des commentaires est parfois négligé.

Tous mes commentaires ne sont pas du type "pourquoi", mais beaucoup le sont.
Voici des exemples tirés d’un fichier source (Delphi):

// For easier access to the custom properties:

function GetPrivate: Integer;   // It's an integer field in the external program so let's treat it like that here

// The below properties depend on the ones above or are calculated fields.
// They are kept up-to-date in the OnEventModified event of the TTSynchronizerStorage
// or in the ClientDataSet.OnCalcFields of the TcxDBSchedulerStorage.DataSource.DataSet
property IsModified       : Boolean   read GetIsModified   write SetIsModified;
property IsCatTT          : Boolean   read GetIsCatTT      write SetIsCatTT;
property IsSynced         : Boolean   read GetIsSynced     write SetIsSynced;

lLeftPos := pos(' - [',ASubject); // Were subject and [shiftnaam:act,project,cust] concatenated with a dash?

// Things that were added behing the ] we will append to the subject:

// In the storage the custom value must also be set for:
Self.SetCustomFieldValueByname(cCustFldIsCatTT,Result);

// When we show the custom fields in a grid, the Getters are not executed,
// because the DevEx code does not know about our class helpers.
// So we have two keep both properties synchronized ourselves:

// lNewMasterEvent was set to usUpdated, overwrite because we added:
if ARepair then
  lNewMasterEvent.CustUpdateStatus := usRecreated

// The source occurrence date may have bee changed. Using GetOriginalDate we can retrieve the original date,
// then use that for creating a target occurrence (and update its date):

lNewTTOccurrence.CustSyncEntryID := cSyncEntryID0;    // Backward compatibility with old sync methode

// Single event became recurring or vice versa; replace entire event

// In contradiction to CopySingleEventToTimeTell, CopyMasterEventToTimeTell does not have a ANewStatus parameter
// because master events are always added.

Notez que (mon) pourquoi les commentaires précèdent généralement le code qui va le faire (donc se terminent par deux points).

Certains ont des commentaires expliquant uniquement ce qui se passe, par exemple, lorsqu'un processus comporte de nombreuses étapes comportant un regroupement logique (et que le code n'est pas remodelé pour le montrer automatiquement), je commenterai comme ceci:

// Step 1. Initialization

Je comprends que le POURQUOI est la raison pour laquelle vous faites quelque chose d'une manière peut-être étrange ou peut-être illogique, en raison des circonstances données qui l'exigent. Le HOW peut être vu dans le code lui-même, aussi étrange soit-il, même si le code n'a pas de "sens". La CE QUI est probablement mieux dit au début de la documentation classe / fonction. Cela vous laisse donc ajouter le POURQUOI , où vous expliquez tout ce qui ne figure pas dans les COMMENT et QUOI, et les manières particulières que vous devez suivre pour des raisons indépendantes de votre volonté.

Bien sûr, ce n'est pas toujours le cas, en dehors du pays des licornes et des arcs-en-ciel ...

COMMENT:

foreach($critters as $creature) {
   $creature->dance();
}

QUOI:

/* Dancing creatures v1.0
 * 
 * The purpose of this is to make all your critters do the funky dance.
 */

foreach($critters as $creature) {
  $creature->dance();
}

POURQUOI:

// We had to store the items in an array of objects because of _____ (reason)
foreach($critters as $creature) {
   $creature->dance();
}

J'ai appris à TOUJOURS écrire des commentaires dans les fichiers d'en-tête C ++ (car ce n'est pas toujours clair CE QUE fait une fonction, même si le nom lui donne un bon indice), surtout si vous transmettez une API à d'autres développeurs ou utilisez un outil d'autodoc tel que doxygen.

Donc, pour moi, un commentaire typique ressemble à quelque chose comme:

/*** Functionname
/*   What happens here
/*  [in] Params
/*  [out] params
/*** 

La seule fois où j'ai utilisé les commentaires WHY, c’est quelque chose de difficile à saisir et parfois même au programmeur, comme "NE PAS TOUCHER CETTE!! Parce que ..." ou "LE PROGRAMME CASSERA SI LA LIGNE EST SUPPRIMÉE ..."

Les solutions de contournement, les piratages et les comportements étranges sont éligibles aux critères POURQUOI à mes yeux ...

Un exemple très bon et même hilarant est cette "solution de contournement" pour du code gâché écrit par une personne nommée Richard, quelqu'un d'autre l'a emballé et a expliqué pourquoi dans les commentaires ... https://stackoverflow.com/a/184673/979785

Malheureusement, il y a plusieurs fois où vous êtes obligé d'envelopper bull **** parce que vous ne pouvez pas toucher à l'original, soit parce que "ça a toujours été comme ça" ou que vous n'avez pas accès ou ... eh bien, vous ne pas avoir le temps de réparer l'original pour le but n'est pas vraiment admissible pour les frais généraux.

Le code est censé spécifier un plan d'exécution. De cette façon, le suiveur de programme (ou le compilateur) peut déterminer ce qu'il faut faire et comment le faire. Ce qui est divisé en étapes que le suiveur de programme peut suivre. Les étapes primitives sont le comment.

L'intention du codeur est une autre affaire. Dans un code simple, clair et simple, l'intention est évidente. Tout lecteur humain raisonnablement compétent arrivera à l'intention d'un bloc de code, simplement en lisant le code. La plupart du code devrait se lire comme ceci.

Parfois, la relation entre l'intention et le plan est obscure. Le code révèle le quoi et le comment, mais pas le pourquoi. C'est alors que les commentaires révélant l'intention en valent la peine. L'intention du programmeur est le pourquoi.

Si ce problème se pose actuellement, nous allons parcourir des procédures stockées et des vues à l'aide d'un modèle de données complexe et quelque peu compliqué.

Nous avons (nombreux) des sélections composées comme "Cas où x.account n'est pas nul et x.address dans (sélectionnez l'adresse de fedex) puis x.account sinon y.account end" et une productivité attendue bien qu'il n'y ait pas de temps à perdre. tout pour lire tout le code source. Et cet exemple a en quelque sorte un sens, mais il reste impénétrable.

Les commentaires expliquant pourquoi dans fedex, alors x et sinon, y - fait la lumière sur l’ensemble du système et, lorsque nous en lisons suffisamment, nous commençons à l’obtenir. Et ceci est simplifié et il y a des centaines ou des milliers de déclarations similaires. Mon cœur brille chaleureusement à qui que ce soit le gentil développeur de 2007 qui a mis ces raisons.

Alors, oui, modèles de données complexes et complexes, procédures de sauvegarde et procédures stockées avec plusieurs chemins d'accès valablement nommés, veuillez nous dire pourquoi, s'il vous plaît, l'amour de D.ieu.

Je viens d'écrire ce commentaire; c'est un exemple concret d'expliquer pourquoi une ligne de code est ce qu'elle est, et en particulier pourquoi je l'ai modifiée.

La méthode examine les données stockées et évalue si elles sont complètes à la date d'aujourd'hui et à la date de début à l'autre.

// In principal, this should be ">=", as we may have data up to the account start
// date but not complete for that day; in practice, 98% of the time if we have
// data for the start date it *is* complete, and requerying it would be a waste
// of time.
while (endDate > accountStartDate)
    ...

Comme vous pouvez probablement le deviner, l'opérateur supérieur à était un opérateur supérieur ou égal. Le commentaire explique pourquoi l'ancienne valeur a un sens et pourquoi la nouvelle valeur est meilleure. Si quelqu'un regarde cela à l'avenir, il verra que l'utilisation de ">" n'est pas un oubli, mais une optimisation. Ils peuvent ensuite le modifier ou le quitter, en fonction des besoins de l’époque.