Discussion :

[kisitomomotene]

Dans le premier cas, le commentaire peut permettre de comprendre le code & donc de savoir s'ils sont synchronisés.
Et puis il y a le cas où le code est incompréhensible si on ne sait pas d'avance ce qu'il est sensé faire.

Dans tous les cas les commentaires ne sont pas censés faire l’économie d'une lecture du code. Et ils sont censés donner des informations complémentaires au code, des informations qui seraient difficiles, et pas évident à retrouver en lisant le code.

L'utilisation des techniques de programmation par contrat, l'utilisation des assertions, et l'utilisation des test automatiques offrent des solutions plus robustes et fiables quant aux compléments censés améliorer la compréhension du code, et avec l'avantage de permettre une certain contrôle automatique de la synchronisation du code et de ses "commentaires"

[ALT]

J'ai dit le contraire ?

[kisitomomotene]

J'ai dit le contraire ?

Non, je ne faisais pas une critique "négative" de votre réponse, j'y apportais plutôt plus de précision.

[deuz59]

Toujours les mêmes débats sur le bon/mauvais code => au final difficile de trancher

Cette notion est d'abord importante quand on travaille à plusieurs sur le même code. Il s'agirait donc d'abord qu'une équipe qui intervient sur un même code définisse dès le début une convention à respecter selon les préférences/expérience de chacun et en adéquation avec les pratiques de l'entreprise.
Des outils permettent de valider par exemple la forme, je ne suis pas certain mais il me semble qu'on peut aller jusqu'à interdire la compilation en cas de non respect sur certains IDE.
Le mieux serait encore que chacun puisse faire comme il le souhaite et au moment du commit, remise en forme automatique selon la convention de l'équipe.


Ensuite c'est surtout l'expérience qui permet d'évaluer ce qui est une bonne pratique ou non et surtout pourquoi (compromis apport/inconvénients à étudier selon les cas).
Je vous conseille vivement la lecture du livre suivant qui permet de profiter de l'expérience de son auteur : http://www.pearson.fr/livre?GCOI=27440100643800
Ce n'est pas la panacée, encore une fois à relativiser selon son environnement mais cela à le mérite de mettre les choses à plat et ainsi mieux percevoir les différents enjeux de la qualité de code et des pratiques.

Pour en revenir aux débats en cours et en s'inspirant de cet ouvrage (qui pour beaucoup reprenait des constats personnels mais que j'avais peut être du mal à organiser, à clarifier) :

• Une méthode ne doit faire qu'une et une seule chose, 10 à 12 lignes me paraît encore énorme comme limite
• "Un bon commentaire est un commentaire qui n'a pas besoin d'être écrit" => si le chaque méthode ne fait qu'une seule chose et est correctement nommée sans prendre plus de 2 voir 3 arguments (rien de pire qu'une méthode dont le code exécuter est dicté par un boolean en entrée), le code s'explique de lui même. Et comme déjà évoqué dans le débat : un commentaire se désynchronise trop rapidement du code pour rester pertinent sur du long terme (les commentaires auront une utilité pour expliquer par exemple des choix de programmation non triviaux mais surtout pas pour expliquer ce qu'on a voulu faire ou ce qu'on ferait mieux de faire : dans ce cas autant le faire à la place d'écrire le commentaire)
  ==> sans compter qu'un commentaire "pollue" la lecture du code (par exemple : plus besoin de polluer les fichiers sources avec des commentaires à rallonge en début de fichier pour lister l'historique des modifications comme le faisaient jadis nos ainés, les outils de gestion de source comme CVS sont là pour ça !!)
  ==> et la javadoc : si vous ne développez pas une API à destination de tiers, est-ce vraiment utile ??? combien même quel intérêt de polluer le code pour indiquer ce que font des méthodes suffisamment spécialisées pour ne pas être ambigües ???

Combien de fois j'entends des arguments du genre "t'as tout complexifié en démultipliant le nombre de classes/méthodes"
==> un besoin complexe nécessitant un algorithme complexe ne pourra s'écrire en 2 lignes
==> tout écrire dans une seule classe peut sembler être plus simple pour s'y retrouver mais qu'est-il le plus compliqué : scroller son IDE en faisant 1000 allers retours pour tenter de trouver un point précis de l'algorithme ou naviguer dans les packages aux classes spécialisées ?

Rien de plus rageant que de devoir intervenir sur un point précis d'un programme ce qui devrait demander quelques minutes mais de devoir finalement devoir comprendre tout l'algorithme en faisant des aller/retour dans le code durant de longues heures/journées (là d'accord s'il y a qques commentaires ils pourront être d'une grande aide...ou nous agacer davantage en nous induisant en erreur...là encore un code bien architecturé sans commentaire sera préférable, non ?)
==> si le code est bien organisé en respectant certaines règles (responsabilité unique, découplage....), la maintenabilité ainsi que son évolutivité n'en sera que meilleure
==> les langages dit modernes ou évolués résident sur un seul principe : l'abstraction (on s'abstrait des caractéristiques bas niveaux pour plus facilement/rapidement mettre au point des programme plus complexes)
==> tout programme utilisant ces langages devraient donc permettre de facilement s'abstraire de telle ou telle préoccupation pour ainsi pouvoir se focaliser facilement et rapidement sur un point précis, or souvent on doit chercher à comprendre non seulement tout ce qui est fait mais aussi comment ça l'est !!!
==> les autres avantages de bien structurer en décomposant par préoccupations unitaires sont qu'on comprend/analyse mieux ce qu'on fait et pourquoi, mais aussi de faciliter la mise en place de tests unitaires justement



Pour conclure, un jeune développeur arrivera plein de bonnes attentions mais dictées par l'apprentissage des langages et des contraintes d'écoles (je suis donc assez d'accord avec la conclusion de Paul Vick), et non par la réalité et l'expérience du travail en équipe. Il est donc impératif de bien les sensibiliser à ce qui est du "bon code" (et donc en avoir conscience soit même), les contraintes qui nécessite telle ou telle attention durant les développements afin qu'il puisse rapidement se poser les bonnes questions (souvent ce ne sont pas les réponses apportées qui sont mauvaises, mais juste qu'on ne sait pas se poser la bonne question)

[mtroya]

Règles d'or complémentaire :


NE JAMAIS TRAVAILLER SUR UNE VERSION D'EXPLOITATION - VERSION DE TEST
Si des développeurs expérimentés commettent parfois la faute de le faire par orgueil et prétention, un débutant doit TOUJOURS créer une version de test et attendre al validation du client pour mettre ses modifications sur la version d'exploitation, qu'il s'agisse d'un logiciel ou d'un site web.


METTRE A JOUR SA BIBLIOTHÈQUE PERSONNELLE
Lorsqu'on crée des méthodes, on ne se rappellera pas forcément des mois ou années après tout ce qu'on a créé.
Dès que l'on crée une nouvelle méthode qui pourrait être utile dans des programmes ou sites ultérieurs, le mettre dans une fichier avec un nom explicite du genre bibliotheque_AGL

[lod101]

Ben moi, si demain, j'ai à nouveau un débutant qui vient bosser sur mon projet, je lui placarde en gros ces 7 règles sans aucun problème (et à moi également). Naturellement je n'oublierai pas de citer la dernière phrase de l'article original (qui a été zappée ici) : "You may go beyond these rules after you have thoroughly understood and mastered them". Faut bien s'emanciper, non !?!

C'est quand même moi qui vais relire et essayais de comprendre son code à ce débutant. Donc sachant que j'ai mon propre code à débugger, j'ai pas envie de passer trop de temps à corriger le sien (je rappelle que c'est un "débutant"...). Ces règles collent parfaitement à mes contraintes...

- Les règles 1 et 2 devraient m'éviter de gros mal de tête
- La règle 3, malgrè son évidence, est interprétable selon le contexte :

• S'il a le droit de "commenter" sa "fantaise" alors il peut se permettre de l'écrire. Si ça dépanne tout le monde on va pas s'en priver. Y'a quand même des contraintes à respecter (delais, budget...). Il aura éventuellement tout le temps de la comprendre plus tard.

• S'il n'a pas le droit de commenter son code (y' a des puristes qui pensent que c'est pas nécessaire, si si c'est vrai !!!) alors la "fantaisie" est à proscrire, car dans ce cas le code n'est plus maintenable

- Règles 4 et 5 : évident. Tout ce qui n'est pas maîtrisé est à éviter (la MAITRISE de son code...c'est comme ça qu'on devient bon). Les remarques du types "ouai, mais j'ai lu le code et j'ai tout compris, c'est du sûr", j'y crois pas. C'est généralement : je lis la description du bout code qui m'interesse, je copie/colle, je compile, j'execute, ça marche, super, ça c'est fait, je passe à la suite...
- Règle 6 : je reste perplexe comme certains ici... C'est quoi l'abstrait ? Si on parle d'abstraction "logicielle", en effet cela peut être délicat à mettre en oeuvre
- Règle 7 : finalement, la règle qui me semble la moins bonne. Comme unité, j'aurai plutôt utilisé les années.

Ce qui ma surpris à la 1ére lecture des ces règles (comme beaucoup), c'est l'absence d'une règle sur les commentaires. J'en ai déduit rapidement que pour l'auteur c'était une chose forcement innée lorsqu'on code. Le commentaire fait partie du code. En fait c'est du code...Ces 7 règles s'appliquent donc aux commentaires.

Mes règles :
1- Se tenir au projet. Le projet à un but et celui-ci doit-être atteint, il faut le terminer coûte que coûte.
...
5- Ne pas faire n'importe quoi, juste parce que l'on sait que ça marche. L'important est souvent de pouvoir comprendre clairement les étapes qu'effectuera mon programme !

Super comme 1ère règle!!! Totalement en contradiction avec la dernière en plus...

Ces règles sont difficilement applicables.

Ben non !!! Elles sont simples, claires, précises (hormis peut être la 6). Tu lui demandes quoi à un débutant ?

Règle 1 : COMMENTER COMMENTER COMMENTER COMMENTER COMMENTER ...
Règle 2 : AERER le Code (Pas de lignes de 100, 200 ... caractères !)
Règle 3 : SUPPRIMER les parties de code inutilisées où mises en commentaires

Oh oui !!! Entierement d'accord sur ces 3 règles.
+1 sur la 3. Il n'y a rien de pire qu'une ligne de code en commentaire.
Soit elle ne sert à rien et on la supprime, soit on a un doute et on la laisse en commentaire avec un commentaire (certains diront que ça fait beaucoup de commentaires, mais c'est indispensable. On n'est pas toujours sûr de tout...)

qu'est-ce que l'abstrait ?
classe abstraite ? interface ?
dans ces deux cas, la règle va à l'encontre des patterns de base dans la programmation objet

L'utilisation des patterns ne concerne pas les débutants. Donc pas de contradictions.

Hmmm, je crois que Idéalement, un code devrait se suffire en lui même, sans commentaire. Le commentaire pour moi c'est pour expliquer des situations pas du tout évidentes.
On devrait pouvoir lire un programme bien écrit et le comprendre sans avoir besoin de commentaire ni de documentations supplémentaires.

Ben mon "débutant" il a pas intêret à me sortir ce genre de remarque... Le code qui se suffit à lui même ça n'existe pas. Même bon, un code ne doit pas être exempt de commentaires. "Hmmm, je crois que Idéalement...", ça fait beaucoup d'incertitude qui rende donc le commentaire obligatoire

Toujours les mêmes débats sur le bon/mauvais code => au final difficile de trancher

En effet... C'est ça qui est interessant aussi ? Où vais-je, dans quelle étagère, ...?

...

• Une méthode ne doit faire qu'une et une seule chose, 10 à 12 lignes me paraît encore énorme comme limite

Ce qui me semble important sur cet aspect (nb de lignes) c'est l'ordre de grandeur plus que le nb en lui même. C'est important et nécessaire de fixer des règles mais il faut savoir être tolérant...

[*]"Un bon commentaire est un commentaire qui n'a pas besoin d'être écrit" => si le chaque méthode ne fait qu'une seule chose et est correctement nommée sans prendre plus de 2 voir 3 arguments (rien de pire qu'une méthode dont le code exécuter est dicté par un boolean en entrée), le code s'explique de lui même.

Un fois de plus y' a une incertitude ("si") sur la methode "surrealiste" qu'on ne voit jamais (methode qui porte bien son nom, qui fait ce qu'on lui dit de faire, ...). Donc pour lever (ou minimiser) toute ambiguité les commentaires sont obligatoires.

Et comme déjà évoqué dans le débat : un commentaire se désynchronise trop rapidement du code pour rester pertinent sur du long terme (les commentaires auront une utilité pour expliquer par exemple des choix de programmation non triviaux mais surtout pas pour expliquer ce qu'on a voulu faire ou ce qu'on ferait mieux de faire : dans ce cas autant le faire à la place d'écrire le commentaire)

Si le commentaire se "désynchronise trop rapidement", qu'est ce qui va en être des docs ??? C'est plus la peine d'en écrire !!! Un développeur qui fait évoluer le code sans les commentaires n'est pas en encore un bon développeur. C'est donc un débutant, il faut donc rajouter une règle : "Toute modification de ligne de code implique une mise à jour du commentaire associé"

==> sans compter qu'un commentaire "pollue" la lecture du code (par exemple : plus besoin de polluer les fichiers sources avec des commentaires à rallonge en début de fichier pour lister l'historique des modifications comme le faisaient jadis nos ainés, les outils de gestion de source comme CVS sont là pour ça !!)
==> et la javadoc : si vous ne développez pas une API à destination de tiers, est-ce vraiment utile ??? combien même quel intérêt de polluer le code pour indiquer ce que font des méthodes suffisamment spécialisées pour ne pas être ambigües ???[/LIST]

Je te répond en particulier mais ma remarque est valable pour tout ceux qui qualifie de "pollution" les commentaires.
Le commentaire est un critère de QUALITE, et la qualité de ce commentaire est directement lié au niveau de compétence du développeur. Alors oui, chez un débutant tu auras des commentaires peut être inutiles et redondants, mais tout bon développeur commente ce qu'il écrit même quand cela semble fastidieux et inutile (c'est une question de maintenabilité, d'évolutivité). La qualité du commentaire évolue en même temps que la qualité du code. C'est d'ailleurs à ça, entre autre, qu'on reconnait un bon développeur

==> si le code est bien organisé en respectant certaines règles (responsabilité unique, découplage....), la maintenabilité ainsi que son évolutivité n'en sera que meilleure

En fait t'es d'accord avec l'auteur :
- Il faut des règles
- Responsabilité unique = règle 2
- Découplage = règle 1 et 2
Ca me va

==> les langages dit modernes ou évolués résident sur un seul principe : l'abstraction (on s'abstrait des caractéristiques bas niveaux pour plus facilement/rapidement mettre au point des programme plus complexes)
==> tout programme utilisant ces langages devraient donc permettre de facilement s'abstraire de telle ou telle préoccupation pour ainsi pouvoir se focaliser facilement et rapidement sur un point précis, or souvent on doit chercher à comprendre non seulement tout ce qui est fait mais aussi comment ça l'est !!!

Trop abstrait pour moi. J'dois être un jeune développeur...

Ce que je demande généralement aussi à "mon débutant" c'est un shéma qui met en évidence l'architecture du logicielle, les dépendances entre les classes. Un diagramme qui tient sur une page et qui n'est pas forcément UML. Ca donne une bonne idée générale du travail effectué et ça lui permet de prendre un peu de recul

[props]

Grosso modo d'accord avec l'auteur. A quelques nuances près :

- concret vs abstrait : je dirais qu'un débutant ne devrait pas s'empêcher de faire de l'abstraction, car cela fait partie intégrante de la POO ! Sinon autant rester en Fortran
Par contre il ne devrait jamais commencer par l'abstraction. Je ne connais pas beaucoup de personnes (y compris chez les cadors) qui sachent vraiment réfléchir à priori de façon abstraite. Dans mes projets je commence le plus souvent par une implémentation concrète, et si j'ai besoin de réutiliser ce code au moins une fois, alors je découple. Cela évite de faire une usine à gaz là où il n'y en a pas besoin.

- Règle 3, je suis plutôt mitigé : quand on travaille sur les frameworks "modernes", il ne faut pas réinventer la roue. C'est le meilleur moyen de complexifier inutilement un projet. Exemple en .NET j'en vois qui s'emm...ent encore à créer des classes de collections spécialisées alors qu'il existe les génériques depuis le 2.0. Pire, certains n'utilisent que les tableaux, en te soutenant mordicus que c'est plus performant qu'un objet liste (c'est la preuve qu'ils ne connaissent pas la logique du framework). Le mieux est encore au final d'utiliser l'interface IEnumerable<>, qui permet de s'affranchir du type de la collection (et on revient dans le débat concret / abstrait).

[_skip]

- Règle 3, je suis plutôt mitigé : quand on travaille sur les frameworks "modernes", il ne faut pas réinventer la roue. C'est le meilleur moyen de complexifier inutilement un projet. Exemple en .NET j'en vois qui s'emm...ent encore à créer des classes de collections spécialisées alors qu'il existe les génériques depuis le 2.0.

Se générer du travail supplémentaire, c'est un sport chez certains.

[RomainVALERI]

Se générer du travail supplémentaire, c'est un sport chez certains.

Sauf qu'en l'occurrence on parle des débutants On se fout un peu que leur projet soit "pro" ou rentre dans les délais ^^ C'est la valeur pédagogique qui est intéressante dans le fait de réinventer la roue...

C'est comme si tu disais à ton gamin de 6 ans qui apprend à écrire : "Pff quel manque de pragmatisme d'apprendre l'orthographe, maintenant c'est le 21ème siècle on a des correcteurs automatiques..." ()

[kisitomomotene]

La meilleur documentation d'une application est son code source, et ses tests automatiques, ils sont les plus fiables.
regardez encore ce code:

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
// calcul du solde d'un client à partir du code client
  public int calculer(String nom){
...
}

Le code en réalité calcule le solde à partir du nom du client, mais le commentaire par erreur dit qu'il calcul à partir du code client. Résultat si quelqu'un se fit uniquement aux commentaires, il risque de calculer le solde d'un client à la place d'un autre! Moralité lire toujours le code et/ou exécuter des tests automatiques ne pas se fier uniquement aux commentaires.

Si la lecture d'un code source permet de retrouver les informations mentionnées dans les commentaires, alors ça augmente le temps de lecture inutilement, et par conséquent complique la maintenance, puisque qu'on perd trop de temps à relire les mêmes choses deux fois: une première fois dans un langage naturel, et une seconde fois dans un langage de programmation.

Conclusion: Ne pas mettre des commentaires inutiles, et dans la réalité peu sont des cas où les commentaires sont vraiment indispensables lorsque une bonne politique de nommage et de structuration du code est mise en place, du moins selon mon expérience personnelle.

[deuz59]

Un fois de plus y' a une incertitude ("si") sur la methode "surrealiste" qu'on ne voit jamais (methode qui porte bien son nom, qui fait ce qu'on lui dit de faire, ...). Donc pour lever (ou minimiser) toute ambiguité les commentaires sont obligatoires.

L'incertitude planera sur toute méthodologie car forcément "si" elle est pas bien appliquée alors elle n'aura pas l'effet escompté...donc l'obligations des commentaires restent tout aussi ambigue (le commentaire n'aura pas d'effet néfaste que "si" le développeur exprime exactement ce qu'il fait dans le code, "si" le commentaire est bien mis à jour à chaque refactoring, "si" il ne pollue pas i utilement, etc ....) Or cela nécessite donc un triple effort code/commentaire/synchronisation avec des risques (confusion,pollution,etc..), au final autant focaliser ses efforts sur la seule chose qu'on ne peut éviter de faire c'est à dire le code qui sera exécuté, en passant du temps à bien respecter les règles de codage qui permette une bonne lisibilité plutot que de rédiger les commentaires on fera d'une pierre 2 coups, on perd un nbre considérable de risques/inconvénients liés aux commentaires tout en gagnant dans la qualité du code exécutable qui constitue la "production" pour laquelle nous sommes rémunérés (on peut passer du temps à bien décrire ce qu'on veut/pense faire dans un commentaire sans pour autant qu'au final ça soit effectivement bien fait, tandis qu'en se focalisant sur le code, on identifie plus facilement ce qu'on fait réellement, le sens/les impacts de nos choix algorithmiques)

Si le commentaire se "désynchronise trop rapidement", qu'est ce qui va en être des docs ??? C'est plus la peine d'en écrire !!! Un développeur qui fait évoluer le code sans les commentaires n'est pas en encore un bon développeur. C'est donc un débutant, il faut donc rajouter une règle : "Toute modification de ligne de code implique une mise à jour du commentaire associé"

Les docs d'un projet et les commentaires dans le code n'ont rien à voir. Après tout dépend des docs dont tu parles (fonctionnels? techniques ?)...dans tous les cas ces docs relève plus de l'étude que de la réalisation et sont à réaliser/maintenir en amont, contrairement aux commentaires qui apparaissent au fil des développements. Le code doit se documenter de lui même mais rester lisible....si je dois me référer au code c'est pour effectuer une modification/vérification d'implémentation d'algorithme et pas de l'algorithme lui même...

Je te répond en particulier mais ma remarque est valable pour tout ceux qui qualifie de "pollution" les commentaires.
Le commentaire est un critère de QUALITE, et la qualité de ce commentaire est directement lié au niveau de compétence du développeur. Alors oui, chez un débutant tu auras des commentaires peut être inutiles et redondants, mais tout bon développeur commente ce qu'il écrit même quand cela semble fastidieux et inutile (c'est une question de maintenabilité, d'évolutivité). La qualité du commentaire évolue en même temps que la qualité du code. C'est d'ailleurs à ça, entre autre, qu'on reconnait un bon développeur

La maintenabilité et l'évolutivité est d'abord lié au code et pas au commentaires...si tu as besoin d'un commentaire pour comprendre un bout de code trop complexes, soit c'est parceque le code n'est pas trivial pour une raison très particulière auquel cas le commentaire peut être utile, mais ce cas est très rare, la plupart du temps les commentaires expliquent un bout de code incompréhensibel à tel point qu'après lectuire du commentaire on est obligé de revoir si le code correspond bien à ce qui est dit et au final trop d"effort qui aurait pu être économisé si le bout de code en question avait été proprement codé (et dans ce cas, le commentaire n'aurait pas eu besoin d'être lu, donc pas utile)
Le critère des commentaires dans la QUALITE est donc pour moi à prendre avec de grosses pincettes car pour ne pas dire que c'est un mauvais critère, je dirais qu'il doit être fortement nuancé....

Trop abstrait pour moi. J'dois être un jeune développeur...

C'est un point difficile en effet à bien percevoir, peut etre parc'il parait souvent normal d'analyser le code dans tous les sens quand on veut chercher à faire une modification, mais la prochaine fois que tu passeras ton temps à chercher ce que qqun a voulu faire en navigant dans tous le code on en lisant des centaines de commentaires, demandes-toi s'il était vraiment normal que tu aies à faire un tel effort et si un vrai code maintenable n'aurait pas du t'épargner cela.....c'est peut etre un peu par fainéantise mais ça a du bon parfois

Ce que je demande généralement aussi à "mon débutant" c'est un shéma qui met en évidence l'architecture du logicielle, les dépendances entre les classes. Un diagramme qui tient sur une page et qui n'est pas forcément UML. Ca donne une bonne idée générale du travail effectué et ça lui permet de prendre un peu de recul

Très bonne idée, mais là encore c'est de l'étude, le commentaire relève du développement :p

[deuz59]

La meilleur documentation d'une application est son code source, et ses tests automatiques, ils sont les plus fiables.

...

Conclusion: Ne pas mettre des commentaires inutiles, et dans la réalité peu sont des cas où les commentaires sont vraiment indispensables lorsque une bonne politique de nommage et de structuration du code est mise en place, du moins selon mon expérience personnelle.

Je plussoie

[deuz59]

Sauf qu'en l'occurrence on parle des débutants On se fout un peu que leur projet soit "pro" ou rentre dans les délais ^^ C'est la valeur pédagogique qui est intéressante dans le fait de réinventer la roue...

C'est comme si tu disais à ton gamin de 6 ans qui apprend à écrire : "Pff quel manque de pragmatisme d'apprendre l'orthographe, maintenant c'est le 21ème siècle on a des correcteurs automatiques..." ()

Sauf que ton gamin de 6 ans apprend à lire, donc oui la valeur pédagogique est essentielle
Le débutant, bien qu'il soit débutant en entreprise, il n'est plus à l'école, s'il participe à un projet pour un client ce n'est pas à but caritatif, le client attend un résultat de qualité, l'entreprise attend un bénéfice

[RomainVALERI]

Sauf que ton gamin de 6 ans apprend à lire, donc oui la valeur pédagogique est essentielle
Le débutant, bien qu'il soit débutant en entreprise, il n'est plus à l'école, s'il participe à un projet pour un client ce n'est pas à but caritatif, le client attend un résultat de qualité, l'entreprise attend un bénéfice

D'où ça sort, cette assertion (en gras) ? Où as-tu lu qu'on parlait des programmeurs "déjà expérimentés" mais qui "débutent en entreprise" ?

[lod101]

...au final autant focaliser ses efforts sur la seule chose qu'on ne peut éviter de faire c'est à dire le code qui sera exécuté, en passant du temps à bien respecter les règles de codage qui permette une bonne lisibilité plutot que de rédiger les commentaires...

Pour moi, les commentaires font parties des règles de codage

[lod101]

La meilleur documentation d'une application est son code source, et ses tests automatiques, ils sont les plus fiables.
regardez encore ce code:

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
// calcul du solde d'un client à partir du code client
  public int calculer(String nom){
...
}

Le code en réalité calcule le solde à partir du nom du client, mais le commentaire par erreur dit qu'il calcul à partir du code client. Résultat si quelqu'un se fit uniquement aux commentaires, il risque de calculer le solde d'un client à la place d'un autre! Moralité lire toujours le code et/ou exécuter des tests automatiques ne pas se fier uniquement aux commentaires.

Si la lecture d'un code source permet de retrouver les informations mentionnées dans les commentaires, alors ça augmente le temps de lecture inutilement, et par conséquent complique la maintenance, puisque qu'on perd trop de temps à relire les mêmes choses deux fois: une première fois dans un langage naturel, et une seconde fois dans un langage de programmation.

Conclusion: Ne pas mettre des commentaires inutiles, et dans la réalité peu sont des cas où les commentaires sont vraiment indispensables lorsque une bonne politique de nommage et de structuration du code est mise en place, du moins selon mon expérience personnelle.

C'est sûr qu'avec des exemples comme ça on peut tout justifier...
Cependant même si le commentaire est incorrect, il reste partiellement intéressant puisqu'il nous dit sur quoi porte le calcul. Vu que le nommage de la méthode est trop imprécis et que cela arrive constament, le commentaire est donc toujours le bienvenu

Moi j'aurais préférer lire :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
8
9
10
11
12
13
/// <summary>
/// Calcule le solde d'un client
/// </summary>
/// <remarks>
/// Le solde doit toujours être positif (par exemple)
/// </remarks>
/// <param name="codeClient">Code client</param>
/// <returns>Solde client</returns>
public int CalculerSolde(string codeClient)
{
     ...
 }

Ben oui, j'ai du code qui risque d'être réutiliser...

Contrairement à toi, moi le commentaire m'évite de lire le code. Si une portion de code à le commentaire "//Addition..." et que pour moi le bug est plutôt dans le bout code "//Soustraction" alors j'aurai gagné un peu temps

[kisitomomotene]

Contrairement à toi, moi le commentaire m'évite de lire le code. Si une portion de code à le commentaire "//Addition..." et que pour moi le bug est plutôt dans le bout code "//Soustraction" alors j'aurai gagné un peu temps

Je ne vois pas en quoi votre commentaire évite de lire le code, car rien ne prouve que ce que vous avez écrit dans le commentaire est réellement ce que votre code fait. C'était cela l'esprit de l'exemple que j'avais donné.
Par contre lorsqu'on écrit des test automatiques, l’exécution du test prouve que le code effectue ce qui est spécifié dans le test

[deuz59]

D'où ça sort, cette assertion (en gras) ? Où as-tu lu qu'on parlait des programmeurs "déjà expérimentés" mais qui "débutent en entreprise" ?

On parle pas de programmeurs déjà expérimentés, en revanche on parle de jeune programmeur, et clairement il ne s'agit pas d'étudiants, mais bien de jeunes programmeurs qui débutent leur carrière professionnelle...après c'est sûr que pour le geek du coin qui développe seul chez lui pour son plaisir et pour lui ou l'étudiant qui fait un TP déjà encadré par son prof, pas besoin de règles particulières, tu fait comme bon te sembles ou tu suis les indications de ton TP

[lod101]

Les docs d'un projet et les commentaires dans le code n'ont rien à voir. Après tout dépend des docs dont tu parles (fonctionnels? techniques ?)...dans tous les cas ces docs relève plus de l'étude que de la réalisation et sont à réaliser/maintenir en amont, contrairement aux commentaires qui apparaissent au fil des développements. Le code doit se documenter de lui même mais rester lisible....si je dois me référer au code c'est pour effectuer une modification/vérification d'implémentation d'algorithme et pas de l'algorithme lui même...

Ben si, tout est lié.
Sachant que des specs figées ça n'existe toujours pas et que, par exemple, cela fait 2 semaines que j'ai commencé à codé pour mon client. Y'a de grandes chances qu'à la première démonstration que je lui fait il me dise "Ouhai c'est super, par contre je me rend compte qu'on a oublié un p'tit truc..." (j'ai pas d' bol mais c'est toujours comme ça moi !!!). Malheureusement pour moi, le "p'tit truc" il n'a pas qu'un p'tit impact sur mon code. Comme ce n'est que la 1ère évol qu'il me demande et que j'aime bien faire les choses correctement, je décris un nouveau usecase (ou j'en modifie un), je refais 2, 3 diagrammes et zou j' me relance dans le code 3, 4 classes en plus et une modife légère au niveau d'un algo tout ça toujours bien commenté évidemment (y'a qques subtilités par ci par là et je dois générer ma doc). Voilà en gros comment ça se passe généralement sur mes projets et voilà pourquoi les docs et le code (donc les commentaires) sont liés pour moi (ça s'appelle d'ailleurs la traçabilité). Tu répéte tout ça tout au long du projet et tu vas vite voir que si tes commentaires ne sont pas à jour c'est même pas la peine de regarder tes docs (c'était le point initial du message)

[deuz59]

Cependant même si le commentaire est incorrect, il reste partiellement intéressant puisqu'il nous dit sur quoi porte le calcul. Vu que le nommage de la méthode est trop imprécis et que cela arrive constament, le commentaire est donc toujours le bienvenu

Le nommage de la méthode est trop imprécis ==> justement d'où la règle de nommer correctement ses méthodes, c'est pas en tentant de contourner par un commentaire que ça règlera le problème, et si le commentaire n'est lui aussi pas précis, on pourra ajouter un autre commentaire peut etre
Et cet exemple reste un exemple pour illustrer les dommages possibles d'un mauvais commentaire qui nous fera l'économie de la lecture du code en nous induisant en erreur, résultat perte de temps et risque d'introduction d'anomalie...au final je préfère ne pas avoir de commentaire et si en effet je dois creuser le code pour comprendre ce que ça fait, au moins je saurais exactement ce que ça fait et pourrais renommer la méthode convenablement (toujours pour citer l'excellent ouvrage "Coder proprement" aux éditions PEARSON, "laisser la place plus propre que je l'ai trouvée" ==> comme chez les scouts...le refactoring permanent permet de garder propre une application , c'est de la qualité au sens amélioration continue)

Contrairement à toi, moi le commentaire m'évite de lire le code. Si une portion de code à le commentaire "//Addition..." et que pour moi le bug est plutôt dans le bout code "//Soustraction" alors j'aurai gagné un peu temps

Si pour toi le bug est plutot dans un bout de code qui a été commenté comme devant être //Soustraction ==> on est sûr de rien et ça aiderait autant d'avoir une methode qui s'appelle "soustraction"

Si tu as une classe qui s'appelle