J'ai effectué une recherche mais je n'ai pas trouvé ce que je cherchais, n'hésitez pas à me lier si cette question a déjà été posée.

Plus tôt ce mois-ci, ce message a été publié:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/

Pour résumer, vous êtes un mauvais programmeur si vous n'écrivez pas de commentaires. Mon opinion personnelle est que le code doit être descriptif et ne nécessite généralement pas de commentaires, à moins que le code ne puisse pas être auto-descriptif.

Dans l'exemple donné

// Get the extension off the image filename  
$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

L'auteur a déclaré que ce code devrait être commenté, mon opinion personnelle est que le code devrait être un appel de fonction descriptif:

$extension = GetFileExtension($image_filename);

Cependant, dans les commentaires, quelqu'un a fait cette suggestion:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/comment-page-2/#comment-357130

L'auteur a répondu en disant que le commentateur était "une de ces personnes", c'est-à-dire un mauvais programmeur.

Quels sont les points de vue de tout le monde sur le code d'auto-description vs le code de commentaire?

Je préfère écrire du code auto-documenté. Un guide pour cela est Clean Code .

Bien sûr, cela ne signifie pas qu'il ne faut jamais utiliser de commentaires - ils ont leur rôle, mais à mon humble avis, vous devez les utiliser avec précaution. Cette réponse antérieure à moi sur SO explique plus en détail mes réflexions sur le sujet.

Bien sûr, comme l'a noté @Niphra, il vaut toujours la peine de vérifier que ce que je pense être propre est vraiment compréhensible par les autres. Mais c'est aussi une question de pratique. De retour à l'université, j'ai écrit des morceaux de code cryptiques simplement en raison de l'utilisation de noms étranges et drôles pour toutes les entités de code, selon mon caprice. Jusqu'à ce que mon professeur rejette une de mes tâches, notant poliment qu'il ne pouvait pas déterminer quel module était le principal :-) C'était une bonne leçon, alors je me suis efforcé de me concentrer sur l'écriture de code toujours plus lisible depuis. De nos jours, je reçois à peine les plaintes des coéquipiers.

Vous ne devez pas documenter ce que fait le code, mais vous devez expliquer pourquoi il le fait.

Aucune astuce de dénomination n'exposera le pourquoi et le pourquoi, vous devez donc ajouter des commentaires pour expliquer le but des différents morceaux de code.

Tous les autres commentaires peuvent être supprimés en toute sécurité.

Je ne crois pas vraiment au code auto-descriptif. Il y a du code plus lisible et du code moins lisible , selon la langue, votre connaissance de celui-ci (en tant qu'auteur d'origine), la connaissance du gars qui le lit et la fonction du code. Mais non, quand même ... il faut le décrire avec un petit commentaire.

Ce qui est clair pour moi maintenant, que je suis dans ce domaine de réflexion ne sera probablement pas clair pour moi dans un an, quand je pense à quelque chose de complètement différent et que je dois utiliser à nouveau cette partie du code.

Alors, commentez votre code. Pas toutes les lignes (mon Dieu, non) bien sûr, mais mettez quelques lignes de commentaires au-dessus d'une fonction / sous-routine / module , ou une partie particulièrement délicate et dites en bref ce qu'il fait. Vous vous remercierez dans un an ou deux.

Heureusement, les deux camps sur cette discussion sont représentés ici, et les arguments pour et contre pour les deux ont été mentionnés.

Je crois que les deux camps ont des arguments qui se chevauchent, et sont en fait d'accord sur la plupart d'entre eux, la façon de les atteindre est un peu différente.

Arguments qui se chevauchent

• Le code doit être lisible.
• Les commentaires ne doivent pas dire exactement la même chose que le code, mais donner un aperçu supplémentaire si nécessaire.
• Tous les noms de variables / fonctions doivent être mûrement réfléchis afin qu'ils donnent une bonne représentation de ce qu'ils sont / font.
• Le code en double doit être évité.

Maintenant, la principale différence est le poids accordé à certains de ces arguments.

Code auto-descriptif

• Les commentaires peuvent devenir obsolètes, donc minimisez leur utilisation, car les mauvais commentaires sont pires que pas de commentaires.
• Les commentaires sont une duplication du code. Tout ce qui peut être écrit en code doit être écrit en code.

Plus de commentaires

• Les commentaires sont plus lisibles que le code. Un anglais simple est meilleur pour décrire quelque chose.

• Le code clair provoque souvent une ambiguïté qui doit être commentée de toute façon. Essayer de décrire cela dans le code entraîne des noms trop longs. De plus, vous êtes constamment confronté à ces informations «supplémentaires» dont vous n'avez besoin que la première fois que vous les rencontrez.

Je crois que les deux camps ont des arguments très valables, mais vous ne devriez pas suivre frénétiquement un camp, juste parce qu'il résout un problème.

Pour démontrer, dans le livre Clean Code , le code est décomposé en de nombreuses méthodes plus petites qui ne sont appelées qu'une seule fois. Les méthodes sont créées pour la seule raison de documenter le code (et TDD plus facile). Il en résulte un enfer fonctionnel . Le code est moins lisible qu'il ne l'était à l'origine, et lors de la refactorisation, aucune pensée n'a été donnée pour encapsuler le code réutilisable.

D'un autre côté, vous voyez souvent des API où chaque fonction est commentée, simplement parce que «les commentaires sont bons». Les choses qui auraient dû être commentées ne le sont toujours pas.

"Je suis désolé mais tu es ce mec."

Je me demande pourquoi il n'aime pas commenter: P

Sérieusement, le codage est trop un art que l'on pourrait véritablement faire une déclaration aussi radicale. Parfois, vous avez besoin de commentaires, parfois de fonctions plus nombreuses et mieux nommées. Habituellement les deux.

Recherchez la programmation alphabétisée comme un style extrême.

La réponse courte, meilleure et correcte

L'idée qu'un "code auto-documenté" bien écrit est tout ce dont vous avez besoin est un anti-modèle et devrait mourir, même s'il fait des exceptions pour les commentaires qui expliquent "pourquoi". C'est un mythe que vous pouvez toujours écrire tout le code pour n'importe quel algorithme suffisamment clair pour que n'importe quel programmeur puisse le regarder et l'obtenir (ou qu'il ne nécessite pas de refactoring ou de temps d'organisation que vous n'avez pas). Plus important encore, le plus souvent, les programmeurs qui pensent écrire du code clair ne le font pas.

Une réponse bien meilleure que les commentaires ne devrait être utilisée que pour expliquer "pourquoi" est que les commentaires devraient:

• expliquer "pourquoi" (bien sûr)
• expliquer "quoi" sur des lignes individuelles uniquement lorsque le code est complexe ou que le but n'est pas clair et qu'il ne peut ou ne vaut pas la peine d'être simplifié davantage
• expliquer "quoi" pour les blocs de code pour accélérer la compréhension et trouver ce dont vous avez besoin

L'explication pour le sauvegarder

Les gens pensent à tort que la seule raison pour laquelle les gens utilisent des commentaires est d'expliquer ce que signifie une ligne de code. La vérité est qu'un objectif important de commenter le code est de le rendre plus rapidepour parcourir votre code et trouver ce que vous cherchez. Lorsque je reviens au code plus tard ou que je lis le code de quelqu'un d'autre, bien sûr, je peux lire et comprendre une section de code bien écrit - mais n'est-il pas plus rapide et plus facile de lire le commentaire en haut en disant ce que fait cette section de code et sauter complètement si ce n'est pas ce que je recherche? Pourquoi rester assis et comprendre le code, même s'il est bien écrit, si vous pouvez jeter un coup d'œil à quelques commentaires et comprendre une fonction entière? C'est pourquoi nous utilisons des noms descriptifs pour les fonctions - personne ne dit que je n'ai pas besoin d'utiliser un nom descriptif pour ma fonction parce que quelqu'un peut simplement parcourir mon code écrit clairement pour voir ce qu'il fait.

Par exemple, si je regarde à travers la fonction de quelqu'un d'autre, est-il plus facile de parcourir ligne par ligne le code pour voir ce qu'il fait ou de regarder trois commentaires bien écrits dans la fonction pour voir exactement ce que fait la fonction et où ça le fait?

Un autre anti-modèle est la surutilisation des fonctions pour commenter votre code. Les fonctions bien nommées sont une partie importante de la documentation du code, mais parfois les programmeurs séparent 2 à 3 lignes de code qui ne seront jamais utilisées nulle part ailleurs dans une fonction à des fins de documentation. Pourquoi la surutilisation des fonctions est-elle meilleure que la surutilisation des commentaires? L'utilisation de fonctions comme celle-ci équivaut à adopter des instructions GOTO - cela crée du code spaghetti qui peut être pénible à suivre.

Essentiellement, lorsque vous travaillez dans un environnement d'entreprise, où les gens partagent constamment du code et où les gens n'ont pas toujours le temps de rendre leur code parfait, quelques bons commentaires peuvent économiser des tonnes de temps et de frustration. Et rappelez-vous, bien que vous puissiez être un gourou qui peut lire le code à une vitesse légère, tout le monde dans votre bureau ne l'est probablement pas.

Eh bien, vous devez également vous souvenir de quelque chose qui est évident ou "auto-documenté" pour vous, peut-être pas pour quelqu'un d'autre ... Peut-être quelqu'un avec moins de compréhension de certaines fonctions. Je commente donc à peu près tout.

Eh bien, le code auto-documenté est que dans cette fonction, vous trouverez:

$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

ce qui est explicite lorsque vous avez le nom de la fonction car il ne s'agit que de deux lignes. Lorsque les choses se compliquent, vous devez soit encapsuler toutes les quelques lignes de code dans une fonction avec un nom descriptif, soit utiliser des commentaires si nécessaire .

Je n'ai jamais compris pourquoi cela devrait être une ou / ou une question, au lieu de et / et. Oui, faites en sorte que votre code soit le plus documenté possible, et oui, ajoutez des commentaires aux parties qui, autrement, ne seraient pas assez clairs.

Les commentaires et le code propre auto-documenté sont différents. Le code concerne la façon de faire les choses. Et les commentaires doivent couvrir la partie pourquoi , qui ne peut pas être expliquée dans le code, quelle que soit votre langue. De plus, si votre langue est très limitée et que vous n'avez aucun contrat, aucune spécification statique et même aucune assertion, les commentaires doivent couvrir les problèmes de limites de votre code.

Dans ce cas, il est facile de créer une fonction descriptive. Mais j'ai lu beaucoup de code créé par de bons programmeurs qui pensaient que leur code était auto-documenté, et ce qui avait été clair pour eux était vraiment déroutant pour moi.

$ extension = GetFileExtension ($ image_name);

Pour revenir à votre exemple, puis-je lui envoyer un tableau de noms d'images ou ne prend-il qu'une seule image? Prend-il en charge tous les types de fichiers, ou seulement certains d'entre eux? Sera-t-il sécurisé la chaîne pour moi, ou dois-je le faire? Si le type de fichier n'existe pas, m'en informe-t-il?

Bien sûr, j'étire un peu celui-ci. Mais je me souviens d'un programmeur qui croyait que audio_bandwidth et video_bandwidth étaient des noms auto-documentés; s'est avéré que l'audio devait être exprimé en octets et la vidéo en kilo-octets. Il a fallu beaucoup de temps pour comprendre celui-là.

L'un n'exclut pas l'autre. Même si votre code est auto-commenté, il peut arriver que vous ayez besoin de commentaires réguliers pour expliquer pourquoi votre code auto-commenté fait ce qu'il fait.

Je ne suis pas d'accord avec cet article et je suis d'accord avec vous dans une certaine mesure. Si vous utilisez de bons noms de méthode, de bons noms de variable et une petite méthode qui font une seule chose, le code devrait être simple à suivre.

Essayez simplement de ne pas être intelligent, car le code intelligent est horrible à lire et à maintenir. Mot-clé: maintenir !

À mon avis, les commentaires devraient décrire le pourquoi et non le quoi. Rappelez-vous que dans ce monde hypothétique parfait, votre code est suffisamment propre pour permettre une lecture facile, vous n'avez pas besoin d'expliquer ce qu'il fait, mais pourquoi vous avez choisi de le faire de cette façon ou de cette façon.

Si vous utilisez un système de contrôle de source, vous pouvez utiliser le message de validation pour faire savoir à tout le monde (et à vous-même) ce que vous avez fait à un moment donné et, plus important encore, pourquoi.

Vous voudriez éviter d'écrire des commentaires comme vous voudriez éviter toute documentation. En ce qui concerne le langage de programmation lui-même, tout le monde fonctionne à partir du même ensemble de vocabulaire et de syntaxe (presque).

Lorsque votre application est destinée à un domaine particulier, il peut être difficile d'amener tout le monde à s'entendre et / ou à établir un vocabulaire commun. On nous apprend à éviter les abréviations et le jargon étendu, mais je vais l'appeler

EBITDA

et pas

EquityBeforeInterestTaxesDepréciationAndAmortization

Si vous n'en connaissez pas, vous ne comprenez probablement pas l'autre. Si la société a une implémentation rare, un commentaire aiderait le prochain programmeur qui pourrait avoir de l'expérience dans le domaine, mais pas cette entreprise en particulier (ce qui rend les choses plus compliquées.).

Je pense que nous devons faire la distinction entre la documentation et expressivité du code.

Lors du débogage ou de la révision du code, vous ne lisez pas un livre. La plupart du temps, vous voulez simplement passer d'une méthode à l'autre et établir des connexions rapides dans votre esprit pour avoir une compréhension de base de ce qui se passe au moment de l'exécution. Ce n'est pas la documentation autour du code mais le expressivité des signatures de code qui importe dans ce processus, leur capacité à être suffisamment significative pour que vous puissiez les identifier immédiatement et les ajouter à votre propre pile d'appels internes. À ce stade, notre cerveau (du moins, le mien fonctionne de cette façon;)) a tendance à considérer les gros blocs de commentaires comme un bruit plutôt que comme une aide. Par conséquent, des commentaires sur une seule ligne, ou mieux encore, des noms de méthode et d'objet auto-descriptifs suffisent ici.

Si vous voulez "lire le livre" d'une classe ou d'une fonctionnalité particulière, c'est bien mieux dans les tests unitaires. Les tests unitaires bien conçus sont par nature révélateurs d'intentions et beaucoup plus documentés (c'est-à-dire explicatifs, détaillés) que les blocs de commentaires les plus épais car ils contiennent 1 / les attentes sur ce que ce code est censé faire et 2 / la capacité de vérifier ces attentes contre le vrai code. Un test de réussite est cent fois plus fiable que n'importe quel commentaire en termes de documentation, car il prouve que ce qu'il affirme est vrai.

Certains codes ne sont tout simplement pas auto-documentés et nécessitent des commentaires d'un collègue humain qui a compris et testé cette pièce. Ce que j'ai ci-dessous n'est pas suffisant pour le comprendre, je pense.

//
// iterative version
//
Node* ReverseList( Node ** List ) 
{

  Node *temp1 = *List;
  Node * temp2 = NULL;
  Node * temp3 = NULL;

  while ( temp1 )
  {
    *List = temp1; //set the head to last node 
    temp2= temp1->pNext; // save the next ptr in temp2
    temp1->pNext = temp3; // change next to privous
    temp3 = temp1;
    temp1 = temp2;
  }

  return *List;
}

Je préfère généralement écrire du code auto-documenté, avec des commentaires peu clairs, car je pense que la plupart du code ne se documentera pas complètement.

À l'université, on nous a appris à reformuler à peu près chaque ligne de code en anglais avec un commentaire (probablement juste pour nous habituer à comprendre ce que fait réellement le code, plutôt que de copier / coller quelque chose et d'espérer le meilleur).

Personnellement, je pense que l'encombrement de votre code l'encombre, le rendant moins lisible que s'il ne s'agissait que de commentaires ou de code. Je suis un codeur C # et les seuls commentaires que je fais tout le temps sont les blocs de commentaires "triple barre oblique" qui sont interprétés en retour dans la documentation IntelliSense. Si je me sens particulièrement coupable d'une façon particulière de faire quelque chose, ou si cela semble particulièrement cryptique, je donnerai une explication supplémentaire, mais c'est à peu près tout.

IMO: Le code auto-documenté est un code dans lequel les noms de variables et de méthodes reçoivent des noms significatifs et contextuels, afin qu'ils décrivent leur objectif.

Si vous avez revu votre code plusieurs fois et que vous n'avez toujours pas trouvé de moyen de faire clairement connaître l'intention à quelqu'un qui connaît le domaine. Réécrivez la fonction. Après tout, ce n'est pas plus de 10-20 lignes. S'il est plus long de réécrire la fonction, c'est trop long et c'est en partie pourquoi elle est illisible :) rinse-repeat

et dans le cas peu probable, on ne sait toujours pas ce que fait le code et vous avez pensé à demander de l'aide à vos pairs. Eh bien, nous vous remercions tous d'avoir aidé Linux à évoluer car c'est le code du noyau que vous écrivez, n'est-ce pas? sinon rincez-répétez par le haut :)

Autrement dit, n'écrivez pas, vous commentez les coder

Consultez Code Complete 2nd edition, p. 128-129.

Les types de données abstraits vous sauveront de cette énigme. Le code d'auto-documentation est la voie à suivre. Les commentaires peuvent être utiles, mais

des entités du monde réel plutôt que des implémentations de bas niveau

vous pouvez éviter d'utiliser des commentaires.

Une chose à propos des commentaires est que vous les écrivez une fois, mais vous ne les voyez pas lorsque vous implémentez la fonction, vous ne les voyez que lorsque vous modifiez la fonction.

Les commentaires sont vraiment utiles lorsqu'ils sont interprétés par l'EDI comme Delphi 2009+ ou JavaDoc fonctionne, mais c'est plus un langage de balisage structuré, donc dans un sens, vous programmez votre documentation, ce qui est très intelligent.

Je crois dans le mantra que le code ne se documente pas lui-même, car vous pourriez être le meilleur programmeur du monde (Ada), et pourtant vous ne comprenez rien à ce qui se passe, mais si vous documentez pourquoi et dans une courte mesure comment votre code fait ce qu'il fait, vous allez vous aider et aider les autres à l'avenir.

Les commentaires sont indispensables. Parce que lorsque vous écrivez du code, vous écrivez pour vos besoins actuels, mais aussi pour les personnes à l'avenir qui doivent lire votre code, comprendre wtf, que faites-vous, et pourquoi, puis comment y apporter des modifications.

Si vous gardez cela à l'esprit, lors du codage / programmation?

Comment puis-je faciliter la compréhension et la modification pour les futurs codeurs de ce code sur lequel je travaille, alors vous ferez du bon travail. A défaut, il est difficile pour les autres de modifier votre code, et n'imaginez pas que ce ne sera jamais le cas, c'est rare ...

Dans la plupart de mes tâches, j'ai toujours dû modifier le code des autres, et le plus horriblement écrit, mal documenté.

Donc, votre habitude de penser que le document de code est lui-même n'est pas de faire preuve de diligence raisonnable.

En tant que programmeur, nous devons pratiquer l'autodiscipline qui peut sembler totalement ar aux programmeurs inexpérimentés, mais nous devons avoir des habitudes, pour éviter toutes les expériences horribles que nous avons eues avec le code d'autrui. Ou même en regardant notre propre code des mois, des années plus tard.

Consultez http://thedailywtf.com, ils ont des tonnes d'histoires humoristiques mais réelles sur les programmeurs qui n'ont tout simplement pas fait preuve de diligence raisonnable.