Discussion :

[Paul TOTH]

je ne met quasiment aucun commentaire... mes lignes de code sont de veritables romans... le nom des composants, variables et autres fonctions sont de veritables post-it... meme un vieux codes de plusieurs mois je replonge dedans comme si je l'avais pondu la veille. Alors bien sur les flemmards de l'ecriture trouverons mes libellés très long et inutiles... mais c'est rudement efficace. Et l'efficacité est un plus en informatique.
FN_transforme_Heures_en_Secondes() et cet exemple est plutot minimaliste.

je signale que je bosse seul... et donc cela me suffit... mais j'ai déjà fait l'experience d'un tiers travaillant sur mon code. Prise en main quasiment immédiate (tout relatif bien entendu) pas eu besoin d'explication.

mouais...je ne suis pas fan, et j'évite le français dans le code car l'absence d'accent rend les choses parfois douteuses et les termes français sont généralement plus long que l'équivalent anglais.

Hour2Sec() me suffira largement

il faut aussi, je pense, faire une distinction entre code compilé et code interprété...si les commentaires et la longueurs des identifiants a peu d'impact sur un code compilé, ce n'est pas le cas pour un script.

[danbo52]

Bon, je ne suis pas un spécialiste d'un langage ou d'un autre, en revanche, pour mes applis ou pour mes clients, lorsqu'il s'agit de développer du calcul scientifique, un minimum de commentaire s'impose.
Essayer de ne pas commenter les techniques de calculs matriciels, les optimisation par recherche de points de cols, vous m'en direz quelques nouvelles, surtout s'il faut revenir dessus quelques mois après réalisation.
Et j'parle pas des calculs différentiels de tous ordres!....parmi d'autres!

J'entends par là que le programmeur n'est pas toujours le chercheur, et son langage doit permettre une maintenance rapide et efficace.

Ouala...it's my advice !

[JELUCA]

il faut aussi, je pense, faire une distinction entre code compilé et code interprété...si les commentaires et la longueurs des identifiants a peu d'impact sur un code compilé, ce n'est pas le cas pour un script.

Bonne remarque en effet, en interprété il y a un véritable intérêt à compresser la formulation. et le commentaire devient indispensable

[Mystcreater]

Pour ma part, je suis totalement d'accord avec ce qui est dit dans cette article; le code devrait être assez claire pour dire ce qu'il fait dans la plupart des cas. Cependant, pour certains cas, c'est totalement nécessaire d'avoir des commentaires mais bien sûr, pour expliquer ce que le code ne peut pas dire.

Par exemple, si vous avec l'instruction suivant:

x = y * 26;

26 est un magic number. Il ne faut pas mettre un commentaire pour le 26, il faut faire une constante qui va dire ce qu'est la valeur 26. Ensuite, il se peut qu'un commentaire soit nécessaire pourquoi c'est 26. Ainsi, 26 peut devenir MAX_COLUMN et le commentaire sera 'Le client a décidé qu'il n'y aurait jamais un traitement de fichier Excel de plus de 26 colonnes.'

Il faut aussi considérer les commentaires xml dans mon cas où je programmes en .Net. Dans ce cas, pour un API publique, les commentaires peuvent s'avérer obligatoire pour permettre aux programmeurs qui vont utiliser votre API de savoir ce que fait chaque méthode de façon plus explicite. Là, est-ce qu'il faut documenter toute les méthodes, propriétés et classes avec ces commentaires. Ça va dépendre de la politique de votre compagnie.

Disons adieu aux méthodes de 100 lignes avec des bloques de code séparés par des commentaires.

[breizh-atao]

Regardez bien une ligne commentée et posez-vous les questions :
- Est-ce que ça va m'aider dans 3 mois ?
- Est-ce juste (durablement) ?
- Est-ce redondant ?

Au moindre doute, on dégage le commentaire et on renomme les identificateurs.

Commenter un bloc de code au sein d'une méthode/fonction/procédure c'est reconnaître qu'il fallait en faire une fonction, alors découpez le code, faites en une fonction bien nommée et le code appelant deviendra lisible. La fonction est petite, la comprendre est immédiat. En C, utiliser l'inlining au besoin (pas d'impact de perf).

Commenter une méthode (au dessus) en explicitant l'algorithme utilisé, OUI, surtout si dans les commentaires on trouve pourquoi on n'a PAS fait comme ci ou comme ça.

Mais commenter `for( i = 0; i < count; ++i ) // pour balayer le tableau`, ça NON !

Les commentaires servent souvent à donner bonne conscience au cochon qui pond un code approximatif. Le commentaire est juste pendant un jour ou deux puis le code est mis au point et le commentaire ignoré devient faux.
J'aime mieux un code brut sans commentaire qu'un code lardé de commentaires dans un anglais de foire.

[-Bi30-]

Le commentaire sert à expliquer ce que fait le code et dans ce cas, s'il n'est pas touché lorsque l'on modifie le code, il peut y avoir inadéquation entre le commentaire et le code.
Mais le commentaire sert également à expliquer le "pourquoi". Pourquoi effectue t-on/ou non telle vérification? Pourquoi peut on avoir tel comportement ? Pourquoi effectue t-on telle action? Etc...
Quand on utilise une librairie Java par exemple, on est content s'il y une java doc intégrée pour expliquer que si tel paramètre est null, alors la méthode renverra une certaine exception.
Bref, le commentaire est utile, s'il est maintenu.

[Mpolo]

Allez coder clairement dans VBA pour Access ou Excel !

Vous avez des formulaires ou des états qui contiennent leur propre code.
Mais si vous écrivez des applications puissantes vous devrez développer des modules qui vont contenir de nombreuses fonctions, qui seront d'autant plus simples qu'elles seront nombreuses.

Ces fonctions pourront être réutilisées dans d'autres parties du code, preuve d'un souci de simplicité et d'optimisation.

Vous vous retrouvez donc avec de multiples procédures disséminées dans divers "feuilles" du code, ceci, du fait même de la conception du langage de programmation conçu par Microsoft pour ses applications.

Il devient donc indispensable de commenter le code, de rappeler quel objet appelle telle fonction, pourquoi il renvoie à telle autre, d'expliquer pourquoi certaines options, parmi plusieurs possibles, ont été choisies, etc...

Plus tard, si vous êtes amené à ajouter de nouvelles fonctions à votre application vous serez bien contents d'avoir commenté votre code et de pouvoir retrouver vos petits.

[r0d]

Et oui ma boite ne cherche pas à faire du bénef... on mange l'argent des autres.

Vive la fonction publique!

[homer242]

Moi, je me sers des commentaires pour :
- signaler quelques choses que le code ne dit pas ;
- créer une esthétique. Et oui, les commentaires ont des couleurs différents dans les IDE, donc ça permet de séparer des blocs de code et de se repérer plus facilement dans le code.

En résumé, je dirais qu'un bon code n'a pas besoin de commentaire mais qu'il en faut pour qu'il soit agréable à lire.

[StefGac]

Code :

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

1
2
3
4
5
6
7
 
       private decimal CalculTVA(decimal pValeurHt,decimal pTaux)
        {
            decimal lValeurCalculer;                     // initialisations
            lValeurCalculer = pValeurHt * pTaux;         // valeur TVA
            return lValeurCalculer;                      // retour TVA
        }

Je veux les commentaires, je lis à droite, je veux le code, je lis à gauche.

D'accord pour votre mise en page, c'est super et très lisible. Pour commenter, sans jeu de mot, voilà ce que j'attendrais en commentaire :
- un exemple réel avec 2 valeurs en exemple genre 345,00 et 1,19 et le résultat envoyé. On pourra me dire qu'il suffit de lire les testcase. Ok, mais naturellement, toutes les applications professionnelles sont complètement testés. ( )
- un commentaire qui m'avertie qu'aucune vérification est effectué par exemple sur la validité du taux de TVA.

Bien sur ce n'est qu'un exemple.

[mllibre]

Il y a peut être une majorité d'applications où le code est assez concret et explicite ce qui fait qu'on peut se passer de commentaires, quoique même si la fonction réalisée est évidente, il peut être intéressant de dire pourquoi on la réalise comme ça. Les commentaires sont intéressant pour fournir le pourquoi des choses. Dans le cas d'algorithmes mathématiques où le code réalise des fonctions abstraites et complexes je commente quasiment chaque ligne, car même en prenant au niveau du code les mêmes noms de variable que dans l'algorithme mathématique, celui-ci est incompréhensible sans explication, ce qui fait qu'au bout de quelques lignes on ne sait plus où on est, ni ce qu'on fait. Pour s'y retrouver lors de la mise au point les commentaires sont indispensables. Et comme on n'est jamais sûr de rien dans le cas d'algorithmes où un test exhaustif n'est pas possible (car il durerait des milliards d'années), on laisse les commentaires à demeure.

[chaying]

Au nom des debutants dont je suis je dirais juste une chose : pensez a nous. Un code selon moi doit avant tout etre pedagogique.
Je comprends bien le desir de certains developpeurs de ne rester qu'entre experts (.net etant proprietaire, ce n'est pas un monde de philanthrope je crois.. ), mais pour ceux qui vivent dans et pour l'open source, les commentaires devraient etre pense pour tous.

Mais ce n'est que l'humble avis du debutant..

[danardf]

Salut.

Perso je ne met pas de commentaires à toutes les lignes.
J'en met pour me repérer dans le code.

// Là... ça sert à çà.

[PapyAccess]

Bonjour
En écrivant en bon français abrégé compréhensible : les variables ,noms des fonctions , noms de routines , de formulaires , d'états , de requêtes et une bonne organisation , vous avez 80% des commentaires
Papy

[ClaudeBg]

Salut
-----

FN_transforme_Heures_en_Secondes()

En longueur ca ne prend jamais plus du double de l'exemple

je ne comprends pas pourquoi nommer une variable avec un nom esoterique ou compressé et mettre un long commentaire pour expliquer son utilisté

Si on est pressé, le commentaire sur "HourToSecond" est plus court que d'utiliser lors de chaque appel "FN_transforme_Heures_en_Secondes". Surtout que tous les langages n'ont pas un environnement mettant l'intellisense à disposition.

personnellement je ne subis aucune pression, j'ai tout mon temps

À l'inverse, si on a tout son temps, pourquoi vouloir chercher à éviter les commentaires qui, selon ton commentaire précédent, prend du temps???

Sinon, des noms explicites c'est pratique, mais si je prends un exemple de ce que ça pourrait donner avec des noms dont tu indiques "une longueur double de l'exemple", ça devient vite galère à relire, genre :

Code :

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

1
2
3
4
5
6
7
private int Ma_Propre_Methode_de_Conversion_de_L'_heure_en_Secondes_avec_parametres(int valeur_en_heure_a_convertir_en_secondes)
    {
        int ceci_est_le_resultat_de_l'operation_en_secondes;
        ceci_est_le_resultat_de_l'operation_en_secondes = valeur_en_heure_a_convertir_en_secondes * Constante_de_conversion_de_heures_vers_secondes;
      ......
        return ceci_est_le_resultat_de_l'operation_en_secondes;
    }

Alors, certes, dans ce cas simplissime précis on comprend. Mais franchement, question simplicité de lecture, j'ai tendance à trouver ceci plus agréable:

Code :

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

1
2
3
4
5
6
7
// converti les heures en secondes
private int HoursToSeconds(int hours)
    {
        var result = hours * C_Hour2Sec     // utiliser constante de conversion
        ....
        return result;                      // retourner résultat
    }

Noms explicites, oui, mais ça doit rester un compromis entre fonctionnalité et lisibilité.

En outre, commenter peut, si nécessaire, parfaitement se faire en deux langues, de même que la documentation. Des noms explicites dans plusieurs langues c'est déjà vachement plus compliqué. Et, si on doit traduire, je pense qu'il sera plus simple de faire traduire un commentaire rédigé correctement et syntaxiquement dans une langue donnée que de demander une traduction d'un nom de méthode.

A+
Claude

[blech ducou]

Une partie de mon boulot consiste à aider les développeurs a corriger ou optimiser leur code.
J'ai peu souvent l'occasion d'avoir des commentaires qui m'aident dans le diagnostique, ou si il y a des commentaires la ligne de code juste en dessous m'en aurais appris tout autant.
La lecture du code est donc toujours le moyen de comprendre ce qui a été fait...
Je pense qu'un code bien écrit ( ie avec nom de variable, de méthode, de classe, de package compréhensible, des classe et des méthodes pas trop longue ...) permet de se passer de la plupart des commentaires (pas tous mais une bonne partie).

[Gecko]

Mes sources sont toujours auto documentées, je ne commente mon code que très rarement.

Après quand je fait un code pour un débutant je commente à mort, mais quand on dev pour soi où d'autres devs expérimentés on peut se permettre de ne rien commenter si le code utilise des noms de variables et méthodes explicites ^^

[irisé]

Bonjour

Tout est question de bon sens !

En reprenant l'exemple donné :

//Extraire les données de l’ancien système
//Transformer les données
//Charger les données dans le nouveau système

et le code correspondant :

Extract();
Transform();
Load();

On voit bien que

Code :

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

Load()

n'a pas le même pouvoir explicatif que

Code :

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

 //Charger les données dans le nouveau système

En fait c'est mieux, beaucoup mieux que :

Code :

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

YouOuh( ) //Charger les données dans le nouveau système

voire que :

Code :

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

YouOuh( )

Dire que le code est auto-suffisant, c'est de la poudre aux yeux : c'est se mentir à soi-même et finalement ne pas écrire de commentaire du tout, ni même y penser!

En fait la bonne formule est peut-être ? :
Ecrire les commentaires avant d'écrire le code. Ce qui permet de réfléchir à son code ...

Et, si on en parle encore alors qu'on en parlait il y a 50 ans, c'est que bon nombre de développeurs écrivent salement encore maintenant ! ...

[04348]

Je suis tout à fait avec cette réflexion,
un code bien écrit soit se lire sans commentaires, les commantaires nuint en général à la lecture, surtout ceux du style "fin de tant que" etc...
Je mets des commentaires uniquement pour des algo très spécifiques

[ael.rowen.terence]

J'ai essayé de lire tous les posts.
Cela n'a fait que confirmé mon point de vue.
Pour ma part, en gros, je n'ai récupéré que des développements crades avec des commentaires qui ne m'ont que rarement servis.
Même si les commentaires étaient justes, il n'empêche, que SEULE la lecture du code est déterminante.
Alors je préfère un code écrit du mieux possible, à un code documenté dont la suspicion de désynchronisation est permanente.

Lorsque je lis un source, je me place du point de vue de la machine. La machine interprète le code et ignore les commentaires, alors je fais tout comme elle.
Si je ne comprend pas ce que fait le code alors : soit le développeur est un mauvais, soit je ne suis pas assez compétent dans le domaine de l'application, soit les deux.