Discussion :

[xetqL]

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.
2- Éviter de passer par New-York pour aller à Marseille. La meilleure solution est souvent la plus simple.
3- Le code doit être explicite et ne demander qu'un minimum de commentaire.
4- Réinventer la roue (Cadre privé) si possible. Cela oblige à un minimum de réflexion.
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 !

[mokbir]

J'ajouterais une 8ème règle: relire le code.

[Skalp]

Ces règles sont difficilement applicables.

Pour moi, la règle d'or de base, facilement applicable pour un débutant et de laquelle découle plusieurs autres bonnes pratiques, c'est :

Do not Repeat Yourself

Ce qui veut dire : ne vous répétez pas.
Voir l'article de Bruno Orsier : Comment éviter les duplications de code : le principe DRY (Do not Repeat Yourself)

[Jay13mhsc]

OK pour ces règles.
Par contre la mise en application de 6 mois, sous entendu, au bout de 6 mois, ça deviendra des réflexes. Ca veut pas dire qu'il faut retomber dans des travers

Autre chose : PLUS DE COMMENTAIRES DANS LE CODE !!!!!
Pourquoi ?
- Parce que quand le code évolue, le commentaire n'évolue que très rarement, et il devient obsolète très rapidement.
- Il vaut mieux utiliser des noms CLAIRS ET PRECIS, et même longs, pour des variables et des méthodes. Une fois cette règle adoptée, les commentaires deviennent inutiles
- S'il y a des commentaires, c'est que la méthode fait plusieurs choses, et donc qu'elle doit être découpée, et avec le point d'avant, le commentaire devient inutile
- Enfin, la meilleure doc d'un code n'est pas le commentaire, mais le tests unitaires, qu'il vaut mieux écrire avant (et pas écrire le commentaire avant de coder !!). Au moins, le TU évolue avec la méthode. Quand on fait du TDD, au lieu de décrire par l'algorithme ce que fait une méthode, on montre comment la consommer, et quels résultats en attendre : c'est un exemple.

Et j'oubliais des pratiques élémentaires : DRY, YAGNI, KISS !!!!!!!!, SoC, SRP et tout l'atiraille SOLID

[Van der Zoot Hector]

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

[shenron666]

[B][SIZE="4"]Règle numéro 1, le programmeur débutant ne doit pas écrire de longues procédures. Une procédure ne devrait pas avoir plus de dix ou douze lignes de code.

règle numéro 0, ne jamais compter en lignes de code

Six, le débutant doit éviter l'abstrait, et toujours opter pour le concret.

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

[olivier489]

Commenter, essentiel à mes yeux aussi!
Surtout via des pré- et post-conditions.

[kisitomomotene]

Par contre, je trouve qu'il manque une règle très importante : les commentaires.

L'idéal serait même de commencer à poser l'algo en commentaire avant de commencer à coder.

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.

Par exemple entre ce code:

Code :

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

1
2
3
4
5
6
7
// calcule le solde d'un client:
//le paramètre nom représente le code du client
void calculer(String nom){

...
}

et celui ci

Code :

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

1
2
void calculerSoldeClient(String codeClient){
}

je trouve que le second code n'a pas besoin de commentaire, et on comprend très bien ce que le code est censé faire à partir de sa signature

[kisitomomotene]

OK pour ces règles.
Par contre la mise en application de 6 mois, sous entendu, au bout de 6 mois, ça deviendra des réflexes. Ca veut pas dire qu'il faut retomber dans des travers

Autre chose : PLUS DE COMMENTAIRES DANS LE CODE !!!!!
Pourquoi ?
- Parce que quand le code évolue, le commentaire n'évolue que très rarement, et il devient obsolète très rapidement.
- Il vaut mieux utiliser des noms CLAIRS ET PRECIS, et même longs, pour des variables et des méthodes. Une fois cette règle adoptée, les commentaires deviennent inutiles
- S'il y a des commentaires, c'est que la méthode fait plusieurs choses, et donc qu'elle doit être découpée, et avec le point d'avant, le commentaire devient inutile
- Enfin, la meilleure doc d'un code n'est pas le commentaire, mais le tests unitaires, qu'il vaut mieux écrire avant (et pas écrire le commentaire avant de coder !!). Au moins, le TU évolue avec la méthode. Quand on fait du TDD, au lieu de décrire par l'algorithme ce que fait une méthode, on montre comment la consommer, et quels résultats en attendre : c'est un exemple.

Et j'oubliais des pratiques élémentaires : DRY, YAGNI, KISS !!!!!!!!, SoC, SRP et tout l'atiraille SOLID

Parfaitement d'accord ça rejoint ce que j'ai dis. Je suis quand même un peu surpris de constater que la majorité des interventions ici mettent trop d'importance sur les commentaire!!!

[_skip]

Parfaitement d'accord ça rejoint ce que j'ai dis. Je suis quand même un peu surpris de constater que la majorité des interventions ici mettent trop d'importance sur les commentaire!!!

Plutôt que d'écrire des hectolitres de commentaires, il est parfois intéressant d'avoir un document à part qui décrit le fonctionnement d'un traitement. Pas forcément la grosse spécification de 20 pages qui devient invalide dès qu'on modifie un nom de variable, mais simplement une description des étapes, comment le déroulement s'effectue etc... C'est l'occasion aussi de fournir des éléments théoriques, d'expliquer brièvement sa réflexion, et pourquoi certaines solutions qui semblent plus élégantes n'ont pas été retenues, et ça, c'est inestimable dans ma branche.

Evidemment c'est gonflant d'aller sous word et tout ça, alors de mon côté j'ai poussé mon entreprise à créer un wiki technique pour la doc, accessible dans son navigateur qui permet de publier facilement de l'information sans se casser la tête avec les styles et la mise en page. Il est aussi facilement possible d'y insérer des liens vers des ressources externes sur le net, une RFC, une étude de cas, le manuel d'une librairie etc...

En résumé, je suis persuadé qu'une doc externe peut souvent se révéler plus intéressante que des commentaires très fouillés et détaillés. Contrairement à ceux-ci, elle donne très facilement une vision **d'ensemble** qui permet à un collègue de dire "ok je vois comment ça marche". Retrouver le fil dans le code est aisé ensuite si les méthodes sont suffisamment bien nommées et bien organisées, beaucoup plus qu'en allant direct sur son éditeur en essayant de découvrir la logique de l'ensemble à l'aide de commentaires.

Sinon, comme ça a été dit ci-dessus, les tests unitaires, en plus de la sécurité qu'ils procurent au fil des itérations, constituent eux-mêmes d'excellents exemples de l'utilisation d'un code.

[Van der Zoot Hector]

Informaticien sur mini système (en RPG sur AS400), si je n'avais jamais fait de commentaires dans mes programmes, comment aurait-je fait pour modifier un Pgm quelques mois ou quelques années plus tard ?
Pour se positionner dans un Pgm (en modif), rien de plus simple qu'un mot-clef dans le commentaire !

Ce n'est pas pour cacher un secret professionnel que de : ne pas faire de commentaires !
Cela peut servir à soi-même lorsque l'on modifie !
Mais : ATTENTION : Un commentaire obsolète doit être effacé ou modifié !

Un COMMENTAIRE est INDISPENSABLE : Il permet la MAINTENANCE du programme !
De plus, lorsqu'un autre intervenant doit travailler dans votre code source, il vaut mieux qu'il passe le moins de temps possible à comprendre ce que "vous avez écrit" !
Quand je vois certains sources de nombreuses dizaines de caractères par ligne, sans commentaires, il m'arrive de passer des heures avant de comprendre ce qu'ils voulaient écrire !!!

Le COMMENTAIRE est non seulement OBLIGATOIRE, mais
"ESSENTIEL" N.B.: Et doit être mis à jour à chaque Modif (pour d'autres, mais aussi pour soi-même !!!

[kisitomomotene]

Informaticien sur mini système (en RPG sur AS400), si je n'avais jamais fait de commentaires dans mes programmes, comment aurait-je fait pour modifier un Pgm quelques mois ou quelques années plus tard ?
Pour se positionner dans un Pgm (en modif), rien de plus simple qu'un mot-clef dans le commentaire !

Ce n'est pas pour cacher un secret professionnel que de : ne pas faire de commentaires !
Cela peut servir à soi-même lorsque l'on modifie !
Mais : ATTENTION : Un commentaire obsolète doit être effacé ou modifié !

Un COMMENTAIRE est INDISPENSABLE : Il permet la MAINTENANCE du programme !
De plus, lorsqu'un autre intervenant doit travailler dans votre code source, il vaut mieux qu'il passe le moins de temps possible à comprendre ce que "vous avez écrit" !
Quand je vois certains sources de nombreuses dizaines de caractères par ligne, sans commentaires, il m'arrive de passer des heures avant de comprendre ce qu'ils voulaient écrire !!!

Le COMMENTAIRE est non seulement OBLIGATOIRE, mais
"ESSENTIEL" N.B.: Et doit être mis à jour à chaque Modif (pour d'autres, mais aussi pour soi-même !!!

J'ai particulièrement dû effectuer des tâches personnelles de maintenance (personnalisation, correction de certain bug etc.) sur des logiciels opensources comme Jboss-Seam, ou L'ERP Adempiere.
Dans ces codes il y a très peu, mais alors vraiment très peu de commentaires. Ces applications sont tellement bien écrite, que leur lecture est un régal. En fait même les quelques commentaires qui s'y trouvent je ne l'ai est jamais lu, ou plus précisément, c'est pas les éventuelles commentaires qui s'y trouvent qui m'aide à comprendre le code et à effectuer la maintenance.

Le danger avec les commentaires, c'est qu'il n'y a pas possibilité de contrôler la synchronisation du code avec les commentaires et mieux vaut un programme non commenté qu'un programme mal commenté!

[Bebel]

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.

A la base on parle quand même de règle pour des développeurs débutants. Et dans ce cas la, je pense qu'il est préférable qu'ils travaillent de façons ordonnées. Les commentaires peuvent aider dans ce sens la.

[dourouc05]

Surtout via des pré- et post-conditions.

Quid de la programmation par contrats dans ce cas ? http://julien-blanc.developpez.com/a...rat_cplusplus/

Selon Wikipédia,

il est reconnu que cette méthode permet quand même d'obtenir des logiciels de meilleure qualité et d'accélérer les phases de débogage.

L'avantage par rapport aux pré- et postconditions en commentaire, c'est que c'est vraiment vérifié à l'exécution, ce n'est pas simplement une idée que se fait le dev tout seul dans son coin, paumée dans un commentaire.

[ALT]

Un bon algorithme (ce qui suppose une bonne réflexion préalable), des commentaires utiles, des procédures courtes, une bonne indentation...
Ce sont des règles que tout développeur, fût-il très expérimenté, devrait suivre.
Autant que je me souvienne, on nous parlait de clarté du code, de réutilisabilité, de modularité, de robustesse, d'efficacité, de conformité aux spécifications...

Bref, rien de nouveau sous le Soleil.

[salve34]

Pour en finir avec les commentaires, je dirai :
- je suis un fervent défenseur du "commenter vos codes!"
- le commentaire n'est pour moi qu'un résumé rapide ou une indication pour un point précis
- la lecture du commentaire ne m'empêche pas de chercher à comprendre le code donc si il y a désynchro je devrais le voir
- pour avoir repris des programmes de stagiaires et autres je suis bien content de leur avoir "gonfler le mou" pour qu'ils commentent leurs codes.

Pour la doc je reconnais que la maintenance est plus difficile à tenir à jour

[bugsan]

En java, quand on parle de commentaire, on sous-entend "javadoc", c'est à dire un commentaire pour une méthode/classe entière.

A contrario, les commentaires au sein même du code sont une mauvaise pratique qui rend ce dernier très difficile à lire. Ce doit être une exception.

[Van der Zoot Hector]

C’était, il y a quelques heures ; la première fois que j’intervenais dans ce forum.
Il est important ( pour moi, informaticien depuis plus de 30 ans, et formateur de surcroit)
d’insister sur la nécessité des commentaires.

Quand vous modifiez un Pgm écrit 5 ou 10 ans précédemment et qu’aucun intervenant ne connaît,
Quel plaisir de trouver des commentaires divisant en paragraphes les différentes actions,
annotant les conditions exprimées dans les boucles multiples (if, or, and,, else imbriquées).
Lorsque l’on vous demande d’ajouter une condition supplémentaire ou de les modifier,
n’oubliez pas de modifier aussi les commentaires !!!

Je vois que le sujet vous intéresse (avec parfois des avis contraires) .

Et je vous remercie de vous exprimer en un langage correct sans fautes d’orthographe.

Passé le cap de mon AS400 en RPG, je me forme sur javascript et PHP.
J’utilise pour cela des « sources » écrit par d’autres.
J’y trouve (en commentaires) beaucoup de langage SMS et une multitude de fautes d’orthographe.
Cela devient impossible à lire !!!

De plus, on trouve des « sources » assez compliqués en très peu de lignes de code.
En effet, l’auteur n’a jamais réussi à passer à la ligne !
Plusieurs centaines de caractères pour une seule ligne.
Aucun paragraphe !
Dans la même ligne, on parle de la chèvre, du chou, du chevrier qui la garde etc. …

Comment pouvoir lire ce code ???

Quel est votre avis ?

[RomainVALERI]

- la lecture du commentaire ne m'empêche pas de chercher à comprendre le code donc si il y a désynchro je devrais le voir

Heu... ça me parait chelou comme idée. Prenons 3 cas :

1) le code et le commentaire sont "en phase" : il t'a fallu "comparer" les deux pour le savoir, donc tu as compris le code indépendamment des commentaires : dans ce cas de figure ils sont donc inutiles ^^

2) le code et les commentaires sont en contradiction flagrante : OK, ça ne te cause pas immédiatement de tort, puisque tu t'en rends compte tout de suite. Une fois de plus, les commentaires ne servaient à rien ici.

3) le code et les commentaires sont légèrement différents et là c'est beaucoup plus moche ( > > )


Rappelle-moi dans lequel de ces 3 cas il était souhaitable d'avoir des commentaires ?

[ALT]

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.