Discussion :

[Amine Horseman]

Certains développeurs font valoir que les commentaires sont redondants, mais selon Newlin, c’est peut-être parce qu’ils oublient qu’il est plus facile de comprendre quelques phrases dans notre langue maternelle que le code directement dans un langage

Pour ma part, j'utilise beaucoup les commentaires et l'espacement entre les différentes partie du code, je le fais principalement pour moi même car j'avais eu à plusieurs reprises à refaire tout un algorithme car je ne comprenais pas mon propre code quelques semaines après. Le fait est que après que cela soit devenu une habitude chez moi, je me suis rendu compte que cela aidait beaucoup mes collègues à comprendre mon code.

[Saverok]

Pour commencer, il faut commencer par définir ce qu'est du code beau
Et là personne, c'est comme avec les femmes, personne n'est d'accord : certains les préfère brune ou blonde, maigre ou athlétique, etc.

Blague à part, ce qui compte surtout, c'est de définir une norme pour un projet (idéalement, pour toute une entreprise quelque soit les projets) et de s'y tenir.
Ainsi, tout le monde s'y retrouve car possède ses points de repère.

[sevyc64]

et si le cas passe inaperçu à la relecture, c'est que l'auteur de la relecture manque de rigueur.

Le seul inconvénient que je constate coté debug/maintenance c'est qu'en général le debugger passe juste la ligne, sans passer "visuellement" dans le cas traité.

Tu viens de donner le cas le plus courant de ce soit-disant manque de rigueur, qui n'en est pas un.
En debug, le problème ne vient pas toujours de la ligne qui fait planter, il peut se situer bien plus haut, sur des lignes ou on y passe un peu trop vite, ou, comme tu dis, sur des lignes offrants plusieurs cas et où en exécutant un peu rapidement on ne voit pas que c'est le mauvais cas qui est traité.

C'est pour la même raison que je n'aime pas les conditions IF...ELSE inline, les lambda, les appels ou cascades d'appel de fonctions dans les paramètres de fonctions, etc... Et malgré tout, j'en écrit quand même quasiment tous les jours.

[koala01]

Salut,

Autant le dire tout de suite, je n'ai pas lu toues les réactions, mais, selon moi :

Effectivement, l'utilisation d'une bibliothèque "éprouvée" devrait être de l'ordre du réflexe (pourquoi se faire ch..er à (mal) faire ce que d'autres ont déjà fait et qui, surtout, dispose du recul nécessaire pour assurer que ca fait les choses correctement grâce à de nombreux utilisateurs ?)

Le style de codage, je suis également totalement d'accord : il faut être cohérent au sein d'un projet, mais il n'y a pas vraiment de "bon" ni de "mauvais" style de codage. Il faut avoir assez de souplesse pour être en mesure de s'y retrouver quel que soit le style utilisé.

Il y a cependant une chose que je n'ai pas lue dans la nouvelle, mais qui me semble importante : le choix des noms (de variables, de fonctions et de types ) : plus on arrivera à exprimer clairement ce que font les choses au travers de leur nom, plus il sera facile de comprendre le code.

Enfin, je ne suis pas du tout de l'avis de l'auteur du blog en ce qui concerne les commentaires . Oui, je suis d'accord avec le fait qu'il est sans doute plus facile de comprendre deux lignes de commentaires écrits dans sa langue natale que deux lignes de code, mais il ne faut pas oublier qu'un code est quelque chose qui évolue en permanence. Le problème des commentaires, c'est qu'ils finissent très rapidement par être "désynchronisés" par rapport au code auquel il font référence, et, à ce moment là, il devient dangereux de se fier au commentaires plutôt qu'au code. Et si c'est pour -- de toutes façons -- devoir lire le code pour s'assurer qu'il fait ce que prétendent les commentaires, autant "zapper" l'étape qui consiste à lire les commentaires, cela fera toujours moins de lecture

Ceci dit, je crois personnellement qu'il y a trois types de commentaires :

• Les cartouches (en gros, ceux qui pourraient permettre la génération automatique de documentation grâce à javadoc ou à doxygen par exemple) : qui expliquent à quoi sert une classe / une fonction / une variable, les pré et post conditions à leur utilisation, le resultat auquel on est en droit de s'attendre, les éventuelles exceptions qui seront lancées etc.
• Les commentaire "pédagogiques" : ce sont des commentaires spécialement destinés aux "débuttants" qui permettent simplement de poursuivre une explication directement à l'intérieur du code
• Les commentaires "paraphrasiques" : les commentaires qui se contentent de dire ce que le code fait, sans apporter la moindre plus value.

A mon sens, seules les deux premiers types de commentaires (cartouches et commentaires pédagogiques) ont réellement du sens :

• Le cartouche parce qu'ils font référence à la partie la plus stable du projet : l'interface qui devra être utilisée pour manipuler les différentes données.
• Les commentaires pédagogiques, au début, pour permettre d'attirer l'attention du récipiendaire sur certains apsects du langage qu'il apprend.

Quand aux commentaires qui se contentent de paraphraser le code, je suis désolé, mais, à mon sens, ils n'apportent strictement rien et pire encore: ils sont souvent plus nuisibles qu'autre chose. Trop souvent un commentaire qui paraphrase le code va être écrit pour une version bien particulière du code, mais ne sera pas mis à jour lorsque le tronçon de code auquel il fait référence sera modifié. On en arrive alors à des situations ubuesques dans lesquels le commentaire dit une chose alors que le code en dit une autre et ca, c'est réellement de nature à nous faire perdre encore plus de temps dans la compréhension du code.

Pour moi, le meilleur commentaire sera celui que l'on ne devra pas écrire : si l'on choisit correctement les noms des variables, des fonctions et des types, si l'on veille un minimum à respecter le principe de la responsabilité unique, le code devrait en permanence arriver à se suffire à lui-même et les commentaire paraphrasiques deviennent de facto inutiles

[ustensile]

Un jour, je suis tombé sur le site un peu barré mais super intéressant et instructif: Sam & Max.
Leur analyse était la suivante et je suis assez d'accord avec eux :

"un bon code est un code qui marche
un bon code est un code qui continue à marcher
un bon code est un code dont on sait pourquoi il marche,
le reste n'est que drosophyle sodomite"

[sevyc64]

Sauf que là, on débat pas de bon code mais de beau code. Ceux sont de choses différentes.

[azgal0r]

Je suis d'accord avec cette règle (et en généralisation, j'aime bien l'opérateur ternaire sur des condition/résultat simples et direct), mais la plupart de mes collègues sont complètement contre.

Je comprendrai jamais les personnes qui préfèrent écrire 10 lignes plutôt qu'une pour une lisibilité inférieure. Je trouve que ça reflète un certain état d'esprit. Chez nous c'est une violation sur sonar

[DonQuiche]

Ceci dit, je crois personnellement qu'il y a trois types de commentaires :

• Les cartouches (en gros, ceux qui pourraient permettre la génération automatique de documentation grâce à javadoc ou à doxygen par exemple) : qui expliquent à quoi sert une classe / une fonction / une variable, les pré et post conditions à leur utilisation, le resultat auquel on est en droit de s'attendre, les éventuelles exceptions qui seront lancées etc.
• Les commentaire "pédagogiques" : ce sont des commentaires spécialement destinés aux "débuttants" qui permettent simplement de poursuivre une explication directement à l'intérieur du code
• Les commentaires "paraphrasiques" : les commentaires qui se contentent de dire ce que le code fait, sans apporter la moindre plus value.

Il manque :
* Le commentaire contextualisant, le plus important. Celui qui t'explique quel est le problème à affronter (en mettant en avant les cas particuliers) et justifie le choix de la solution présentée. Généralement situé avant une classe, voire une méthode complexe. S'il ne doit y avoir qu'un seul commentaire dans le fichier, que ce soit celui-ci.

* Le commentaire explicitant, celui accolé à un code et qui explicite une information implicite, généralement un couplage entre deux fragments distants du code. "Nous avons besoin d'ajouter cette information ici car la méthode XYZ en aura besoin." Souvent cela dénote un problème du code, parfois c'était la moins pire des solutions. Et parfois il se confond avec le commentaire contextualisant quand l'information implicite est extérieure au code ("le périphérique bogue si on n'envoie pas d'abord ce code")

Quant aux cartouches ils sont très souvent inutiles pour moi (presque toujours "paraphrasique" selon ta terminologie), n'ont généralement de valeur que pour les débutants, et cet excès d'information inutile finit par masquer les rares morceaux d'information utiles puisque plus personne ne les lit. La systématicité de ces cartouches est pour moi une mauvaise pratique malheureusement répandue : la bureaucratie procure un sentiment de sécurité.

[Saverok]

Je comprendrai jamais les personnes qui préfèrent écrire 10 lignes plutôt qu'une pour une lisibilité inférieure. Je trouve que ça reflète un certain état d'esprit. Chez nous c'est une violation sur sonar

Et inversement, je ne comprends pas les personnes qui préfères condenser les instructions sur une seule ligne avec une grosse perte de lisibilité plutôt que sur 3-4 lignes.

C'est comme partout, l'art est de trouver le bon équilibre.

[koala01]

Il manque :
* Le commentaire contextualisant, le plus important. Celui qui t'explique quel est le problème à affronter (en mettant en avant les cas particuliers) et justifie le choix de la solution présentée. Généralement situé avant une classe, voire une méthode complexe. S'il ne doit y avoir qu'un seul commentaire dans le fichier, que ce soit celui-ci.

Mais il n'a rien à faire dans le code... Dans un document de conceptin quelconqute, sans doute

* Le commentaire explicitant, celui accolé à un code et qui explicite une information implicite, généralement un couplage entre deux fragments distants du code. "Nous avons besoin d'ajouter cette information ici car la méthode XYZ en aura besoin." Souvent cela dénote un problème du code, parfois c'était la moins pire des solutions. Et parfois il se confond avec le commentaire contextualisant quand l'information implicite est extérieure au code ("le périphérique bogue si on n'envoie pas d'abord ce code")

Qui met en évidence une mauvaise organisation du code, et qui devrait donc impliquer une refactoring en profondeur

Quant aux cartouches ils sont très souvent inutiles pour moi (presque toujours "paraphrasique" selon ta terminologie), n'ont généralement de valeur que pour les débutants, et cet excès d'information inutile finit par masquer les rares morceaux d'information utiles puisque plus personne ne les lit. La systématicité de ces cartouches est pour moi une mauvaise pratique malheureusement répandue : la bureaucratie procure un sentiment de sécurité.

A mon sens, non (mais bon, tout le monde est libre d'avoir son propre avis)... Lorsque l'on utilise une bibliothèque quelconque, il est -- à mon sens -- important de pouvoir retrouver les différentes fonctionnalités et de pouvoir choisir celle qui nous intéresse dans une situation donnée. Les cartouches sont d'excellents outils pour y arriver (en plus d'offrir des possibilités de génération automatique de documentation )

Maintenant, je développe essentiellement en C++ qui tend à séparer bien d'avantage la déclaration et l'implémentation d'une fonction (par rapport à d'autres langages qui regroupent les deux). Cela a --très certainement -- une incidence directe sur mon point de vue

[DonQuiche]

Mais il n'a rien à faire dans le code... Dans un document de conceptin quelconqute, sans doute

Tu connais beaucoup de dévs qui vont chercher les docs de conception chaque fois qu'ils ouvrent un fichier source ? Et qui les mettront toujours à jour sans faillir ?

Pas moi.
Les bonnes pratiques devraient être pensées pour des humains, pas pour des borgs.

Et puis je ne te dis pas d'en tartiner des pages : quelques lignes suffisent bien souvent. Si le lecteur a besoin de détail tu peux toujours le renvoyer vers un document approfondi.

Qui met en évidence une mauvaise organisation du code, et qui devrait donc impliquer une refactoring en profondeur

Parfois oui, je l'ai dit. Pas toujours.

Il y a tout simplement une limite à la quantité totale d'information que tu peux raisonnablement expliciter via deux ou trois identifiants (un de type, un de méthode, etc). Et puis il y a les bibliothèques externes. Et tout ce qui ne relève pas du code.

Maintenant, je développe essentiellement en C++ qui tend à séparer bien d'avantage la déclaration et l'implémentation d'une fonction (par rapport à d'autres langages qui regroupent les deux). Cela a --très certainement -- une incidence directe sur mon point de vue

Selon mon expérience cela n'a absolument aucun impact sur le design de l'API, sauf lorsque la fainéantise s'en mêle et qu'un dév cherche à éviter d'avoir à écrire une définition.

En revanche cela a un impact très négatif sur la lisibilité de la source puisque celles-ci vont souvent du détail (méthodes feuilles en haut) vers la vue d'ensemble (méthodes racines en bas) au lieu de faire l'inverse.

[Jitou]

Lorsque j'étais débutant je voulais constamment tout refaire à ma manière en corrigeant le nommage pour le standardiser mais aussi retoucher la manière de présenter un code logique, ce qui est une perte de temps et contre productif au final (et ce même avec des outils de refactoring puissants). Et puis l’expérience avançant je me suis rendu compte qu'il est beaucoup plus important de respecter un style existant afin d'assurer une cohérence sur le projet. Même si la règle adopté n'est pas optimal et perfectible il ne faut pas chercher à la modifier, sauf si bien sur on en est aux premières lignes de code.

Donc j'adhère complètement à l'idée suivante avancée dans l'article: "Ce qu’il propose donc lorsque vous travaillez sur un projet existant, c’est de suivre les conventions déjà en place."

[ChristianRoberge]

La beauté et l'esthétique sont des critères qualitatifs. Le code est du domaine quantitatif, donc a priori, sans rapport entre un et l'autre. Toutefois, si on regarde de les listings ou les écrans, nous discriminons assez facilement le bons, des mauvais programmeurs. Le manque d'organisation dans un code se voit visuellement. Il y a quelque chose qui choquent nos yeux, qui n'est pas "beau".
À noter qu'avec ce recul, nous ne voyons pas ce que fait le programme. La réécriture de if comme proposé n'a pas d'incidence sur la beauté et les capacités d'un programmeur. Il peut connaître toutes les techniques d'optimisation et de codage, cela n'en fait pas pour autant un programmeur capable de les appliquer convenablement dans un programme. L'organisation et la structurations des idées conduisent habituellement à la "beauté" et l'esthétique, le contraire jamais.

[Laurent 1973]

Toutefois, si on regarde de les listings ou les écrans, nous discriminons assez facilement le bons, des mauvais programmeurs.

Je préfère parler de bon et mauvais codes, que de bon et mauvais développeurs.

Déjà parce que l'on peut être tous amené à un moment, dans un projet et sous la pression, à créer du "code tout pourri": est-on alors automatiquement un mauvais programmeurs?
Pas forcement, on n'a juste pas été dans les meilleurs conditions pour faire du bon travail.
Même de jeunes développeurs qui pourraient être classifier trop rapidement de "mauvais programmeurs" sont dans un situation où on ne leur permet pas de s'améliorer, s'auto-former et donc se rendre meilleur.

Les revus de codes sont justement de bonne pratique pour rendre un "code tout pourri" bien meilleur.
Mais si on commence ce travail, en équipe, pas passer au pilori le développeur qui a réalisé cela, ce ne deviens pas constructif.
Aidons nous plutôt a être tous meilleur, le développement logiciel est un travail d'équipe: jouons collectif.
Malheureusement, cela viens trop souvent de certaines directions qui ne laissent pas suffisamment de temps aux équipes pour faire un travail de qualité.

Après, il y a toujours de personne, que je ne classifierais pas de "mauvais programmeurs" mais de personne ayant aucun capacité à se remettre en question.
Ce n'est pas un problème lier à notre métier mais à la personnalité de ces développeurs.
Là, en effet, ce manque de qualité nécessaire dans l'industrie du génie logiciel est préjudiciable à la fois pour les projets que pour les personnes elle-mêmes.

[Logan Mauzaize]

Peut-on définir des normes d’écriture d’un beau code ?

Comme cité, uniquement dans un contexte donné (projet, client, équipe, entreprise, etc.). Le mieux étant tantôt le plus proche du développeur (ex : projet, pour satisfaire au mieux les habitudes de chaque personne) tantôt le plus global (ex: entreprise, pour les gens travaillant sur une grande variété de projet).
Bref, il n'y a pas vraiment de règle.

Un point qui ne me semble n'a pas été abordé mais, en tant que développeur, on passe beaucoup plus de temps à lire du code qu'à en écrire. Mais on oublie aussi, qu'il y a d'autres intervenants qui vont relire le code ! Vos collègues qui appellent votre module, les relecteurs (ex : responsable technique). L'esthétique du code ne doit donc pas uniquement être orienté "développeur".
Bien que sûrement développeur, les "autres" ont une approche et un regard différent sur le code, et il me semble important d'en tenir compte.

« Il n'y a pas de style de code correct », il faut être cohérent selon un bloggeur

Ca peut paraître "idiot" mais je me souviens qu'en tant que débutant c'est une logique qui m'échappait. Ca peut toujours être utile de le rappeler.
Mais le problème prend de l'ampleur quand on récupère la maintenance d'un projet étant censé être soumis à certaines règles de codage mais que celles-ci n'ont jamais été appliquées.
Dans ce cas, j'aurais tendance à préconiser de faire un formattage massif avec un outil avant de commencer tout développement. Sinon le suivi des modifications, les merges et autres joines de la gestion de configuration deviennent un enfer.
Même principe pour les règles de nommage et autres règles n'ont traitées automatiquement. Essayez tant que possible de faire le ménage avant de commencer réellement à travailler. Si cela doit se faire au fil de l'eau, prévoyez dans ce cas de travailler sur des parties bien distinctes pour éviter tout conflit.

L’écriture d’un code qui permet de satisfaire les exigences fonctionnelles et de performance a toujours été la première priorité des développeurs.

Pas pour tous

Au-delà de cet aspect, bon nombre de programmeurs s’attardent un peu sur le style d’écriture de leur code pour faciliter la lecture et la compréhension. Cela permet au développeur de repérer plus facilement les erreurs et également de comprendre ce qu’il essayait de faire lorsqu’il revient sur le projet quelques mois plus tard.

En cela je trouve intéressant l'exercice de refactoring "extract method". Cela permet de réfléchir au sens/but d'un morceau de code. Parfois il arrive qu'on retravaille le code de manière moins performante/optimale pour lui donner plus de sens. Bien sûr cela n'est vrai que pour les cas où les performances ne sont pas problèmes (c-à-d le plus souvent !)

Pour lui, c’est une erreur de penser que l’utilisation de commentaires verbeux et d’espaces blancs font de vous un mauvais programmeur. Certains développeurs font valoir que les commentaires sont redondants, mais selon Newlin, c’est peut-être parce qu’ils oublient qu’il est plus facile de comprendre quelques phrases dans notre langue maternelle que le code directement dans un langage. Si ces derniers arrivent facilement à comprendre un code sans commentaire, ils pourraient toutefois gagner du temps à analyser la version commentée. Pour être efficace, le bloggeur pense qu’il est logique de commenter tôt et bien souvent, et les espaces viennent en compléments des commentaires pour faciliter la lecture du code.

Personnellement, j'ai tendance à utiliser les lignes blanches et les commentaires pour structurer le code. Là où j'aurais pu faire un "extract method", mais je préfère garder la linéarité du code pour "préserver" les variables locales et éviter l'enfer de la navigation.
J'ai fait grandement l'expérience de ce dernier point, il y a peu en écrivant un batch d'intégration de nouvelles données. Tout est découpée en petites méthodes : facilité de test / débuggage et relecture des "macros" méthode. Par contre la navigation s'avère un enfer. Ca me fait penser au problème de "callback hell".
Le truc sympas que pourraient implémenter les IDE ca serait peut-être de pouvoir incruster visuellement le code d'une macro (procédure, fonction, méthode) directement au sein du code appelant. Reste à voir comment traiter la substitution des paramètres. Ou alors ce sont simplements les outils de navigation d'Eclipse (Quick outline, Back to ..., Last edit location, Caller hierarchy) qui ne sont pas adapter à ma manière de travailler.

Un autre problème auquel il s’attaque est la guerre autour des conventions de nommage. Pour Newlin, « il n’y aura jamais de gagnant, c’est une guerre inutile. Tout le monde a une préférence sur les conventions de nommage, et certains langages préfèrent massivement un style plutôt que l'autre. La seule chose qui importe est la cohérence. »

Petite trouvaille intéressant concernant le projet sur lequel je travaille actuellement. L'ancien CP (et quelques experts) du domaine, on définit un glossaire avec une forme abbrégée pour chaque mot. On utilise alors les formes abbrégées pour les variables, les paramètres, les attributs et les méthodes (pas pour les classes ou les packages). Ca permet d'avoir des noms relativement court mais très compréhensibles.
Ca demande un peu de temps au début pour rechercher chaque termes mais une fois le vocabulaire assimilé, c'est très efficace.
A noter dans ce glossaire qu'il est également défini des synonymes. Si on recherche un terme approchant cela indique qu'il faut utiliser plutôt tel synonyme.
Bref, un petit principe que je recommande pour ajouter de la cohérence dans vos projets.

Ce qu’il propose donc lorsque vous travaillez sur un projet existant, c’est de suivre les conventions déjà en place. Et si vous débutez un nouveau projet, la logique serait de définir les conventions de nommage que vous souhaitez utiliser, et de vous tenir strictement à cela. Dans le cas où vous travaillez sur un projet dans un langage avec un guide de style, « il est bon de suivre les conventions de nommage définies dans le guide », a-t-il écrit.

Et surtout d'utiliser des outils d'aide au formattage (IDE ou autre) et de contrôle (Checkstyle, Lint, etc.), définir correctement leurs configurations et les partager !
Je compte plus le nombre de projet ou les règles de formattage d'Eclipse n'était pas compatible avec la configuration checkstyle, elle-même non compatible avec la norme de codage du département ... Un comble !

Vous avez peut-être entendu certains développeurs dire que l’utilisation de bibliothèques tierces est une mauvaise chose. Là encore Marc Newlin pense qu’il s’agit d’une erreur de la part d’un développeur qui aime ressentir la fierté d’avoir écrit un code complexe en seulement 2 jours. Newlin pense que si ce dernier avait avant tout effectué une recherche sur Google, il aurait surement trouvé une bibliothèque sous licence MIT/BSD qui fait exactement ce qu’il veut, sinon mieux. Il aurait alors gagné 2 jours pour améliorer son programme, au lieu d’essayer d’avoir la propriété complète sur son code.

Pour Marc Newlin, le plus important, c’est d’écrire votre code de sorte qu’un étudiant en informatique de première année puisse le lire, un beau code se doit d’être simple. Il ajoute également qu’un programmeur éclairé va chercher à être plus productif en étant assez humble pour utiliser des bibliothèques tierces si possible. Cela lui éviterait d’écrire beaucoup. Il devrait également utiliser le plus de commentaires possibles.

Je vois déjà un conflit d'intérêt : utiliser des bibliothèques et écrire un code pour débutant. S'il est débutant, il est peu probable qu'il connaissance la bibliothèque.
Et plus, vous utiliserez de bibliothèques et moins il y aura de chance qu'il les connaisse toutes ! Si on suppose qu'il y a 90% de chance qu'un débutant connaissance une bibliothèque quelconque, la chance qu'il en connaisse trois n'est que de 73% (0.9^3)

Qu'est ce qui caractérise un beau code selon vous ?

D'un point de vue générale : que l'on puisse distinguer correctement les différentes parties (lecture, recherche, navigation). C'est assez abstrait mais je pense que c'est un principe de base à garder en mémoire quand on se penche sur l'esthétique de son code.

Le style de codage, je suis également totalement d'accord : il faut être cohérent au sein d'un projet, mais il n'y a pas vraiment de "bon" ni de "mauvais" style de codage. Il faut avoir assez de souplesse pour être en mesure de s'y retrouver quel que soit le style utilisé.

Le problème c'est que si ... il y a des mauvais style (dans l'absolu) et d'autres qui sont "mieux". Pour faire l'analogie avec les femmes, on trouvera certaines femmes pas nécessaires à son goût mais on ne pourra pas nier qu'elles sont "jolies".

Il y a cependant une chose que je n'ai pas lue dans la nouvelle, mais qui me semble importante : le choix des noms (de variables, de fonctions et de types ) : plus on arrivera à exprimer clairement ce que font les choses au travers de leur nom, plus il sera facile de comprendre le code.

Le choix des noms est effectivement très important. Mais il peut être difficile d'exprimer deux idées précises dans un seul nom de méthode.

Enfin, je ne suis pas du tout de l'avis de l'auteur du blog en ce qui concerne les commentaires . Oui, je suis d'accord avec le fait qu'il est sans doute plus facile de comprendre deux lignes de commentaires écrits dans sa langue natale que deux lignes de code, mais il ne faut pas oublier qu'un code est quelque chose qui évolue en permanence. Le problème des commentaires, c'est qu'ils finissent très rapidement par être "désynchronisés" par rapport au code auquel il font référence, et, à ce moment là, il devient dangereux de se fier au commentaires plutôt qu'au code. Et si c'est pour -- de toutes façons -- devoir lire le code pour s'assurer qu'il fait ce que prétendent les commentaires, autant "zapper" l'étape qui consiste à lire les commentaires, cela fera toujours moins de lecture

A défaut d'expliquer le code, on peut expliquer comment le lire (contexte d'appel, problématique géré, etc.)

Les commentaire "pédagogiques" : ce sont des commentaires spécialement destinés aux "débuttants" qui permettent simplement de poursuivre une explication directement à l'intérieur du code

Le problème c'est que tu supposes que tout ton code ne requiert qu'un seul niveau (celui de "débutant"), que la plupart des lecteurs seront du même niveau ("débutant") et que tous ceux du niveau concerné vont lire le commentaire ...
Je suis pour ce genre de règle mais l'appliquant régulièrement, je sais ô combien il est difficile de définir une règle.

Les commentaires "paraphrasiques" : les commentaires qui se contentent de dire ce que le code fait, sans apporter la moindre plus value.

Lapsus ou pas, j'ai lu "parasite"

c'est réellement de nature à nous faire perdre encore plus de temps dans la compréhension du code.

Et encore c'est le moindre mal ! Tout comme un mauvais nom de variable, cela peut nous tromper sur sa fonction.

Pour moi, le meilleur commentaire sera celui que l'on ne devra pas écrire : si l'on choisit correctement les noms des variables, des fonctions et des types, si l'on veille un minimum à respecter le principe de la responsabilité unique, le code devrait en permanence arriver à se suffire à lui-même et les commentaire paraphrasiques deviennent de facto inutiles

En fait cela suppose que la spécification fonctionnelle se suffit à elle-même. Or si c'était le cas on aurait plus besoin de développeur Il y a toujours des détails techniques, du cambouis si j'ose dire. Alors il vaut mieux avoir des indications pour nous éclairer.

Quant aux cartouches ils sont très souvent inutiles pour moi (presque toujours "paraphrasique" selon ta terminologie), n'ont généralement de valeur que pour les débutants, et cet excès d'information inutile finit par masquer les rares morceaux d'information utiles puisque plus personne ne les lit. La systématicité de ces cartouches est pour moi une mauvaise pratique malheureusement répandue : la bureaucratie procure un sentiment de sécurité.

Disons qu'il ne faut garder dans le cartouche que ce qui est utile et celui-ci doit permettre de générer une documentation "générale". Les outils comme Javadoc, Doxygen sont de bons candidats pour gérer ces cartouches.
En revanche, je suis d'accord sur le fait qu'il y a beaucoup d'informations inutiles (ex: version courante, auteur de la dernière modification, nom du projet) autant d'information que pour retrouver de manière fiable depuis le gestionnaire de conf.
En revanche toute information utile à avoir dans une javadoc ou dans une infobulle de l'IDE est pertinente sans à avoir ouvrir le fichier d'implémentation.

Mais il n'a rien à faire dans le code... Dans un document de conceptin quelconqute, sans doute Qui met en évidence une mauvaise organisation du code, et qui devrait donc impliquer une refactoring en profondeur

J'ai tendance à apporter toute précision au plus proche du code et réserver la documentation pour les aspects les plus généraux (overview) et tout ce que je ne veux pas répéter dans chaque classe qui implémente un "pattern".

[RPGamer]

Je suis d'accord avec cette rège (et en généralisation, j'aime bien l'opérateur ternaire sur des condition/résultat simples et direct), mais la plupart de mes collègues sont complètement contre.

Dans tous langage de programmation, il y a des mécanismes fondamentaux (turing-complet) et des mécanismes additionnels. Ces mécanismes additionnels sont toujours des spécialisations des mécanismes fondamentaux. Par exemple la boucle for() est une spécialisation de la boucle while() et l'opérateur ternaire est une spécialisation de la structure de condition if(). En général il y a des cas très clairs où le mécanisme additionnel est plus adapté que sa version fondamentale, et d'autres moins. Il est possible d'écrire un code en n'utilisant qu'uniquement des boucles while() mais c'est faire abstraction des outils proposés par le langage et donc témoigne implicitement d'une méconnaissance des outils du langage. Le code est souvent moins beau aussi car la lisibilité apportée par ces mécanismes additionnels fait aussi partie du cahier des charges d'un langage. La boucle for ( : ) parcourant un conteneur en est un parfait exemple.

En l'occurence, cet exemple du PDF correspond exactement à ce pour quoi l'opérateur ternaire est conçu. Evidemment, il ne sera jamais obligatoire d'utiliser un opérateur ternaire au lieu d'une condition "classique" mais dans un cas qui correspond à son profil, utiliser un if() au lieu d'un ternaire induira chez le lecteur éclairé une impression de méconnaissance du langage de la part de l'auteur. Quand à répliquer le retour d'une expression booléenne, c'est tout simplement stupide et plus confusant qu'autre chose pour un développeur expérimenté.