Commentaires

1. Le dimanche 23 mai 2010, 20:56 par Florent Ramière

Argh "Downloads require paid membership of The Java Specialists' Club."

2. Le dimanche 23 mai 2010, 21:06 par Olivier Croisier

Oui, maintenant il faut adhérer au Java Specialists Club pour profiter des webinars et du forum (et probablement de plein d'autres choses intéressantes aussi). Il y a du contenu de qualité et l'accès aux meilleurs experts java mondiaux, le prix est donc raisonnable pour les sociétés qui valorisent leurs référents techniques.

Mais que cela ne t'empêche pas de donner ton avis sur les commentaires !

3. Le dimanche 23 mai 2010, 21:32 par Anzymus

Ah les commentaires! Vaste sujet ...

Je dirais qu'un code bien fait nécessiterait peu de commentaires. Il faut donc que je définisse la notion de code bien fait (pour moi) :

- court : J'aime avoir des méthodes suffisamment courtes pour ne pas avoir à scroller pour la voir entièrement.
- indenté & espacé : Là, ça dépend de chacun, en gros j'utilise le formattage de base d'Eclipse mais j'aime pas quand les lignes sont coupées à la 80ème colonne
- "simple" : on évite l'imbrication de l'opérateur ternaire "parce-que-a-ce-qui-parait-ca-booste-les-perfs". Oui j'ai déjà vu un développeur me justifier ça : a ? (b ? (c ? (x : y) : z) : d )

D'une manière générale, je ne mets aucun commentaire sur les getter/setter/constructeur, autrement dit, un POJO n'aura qu'un commentaire de classe pour expliquer son rôle si c'est un ObjetMetier et les relations avec les autres objets.

Par contre, les endroits où je serai généreux en commentaires, ce sont les méthodes où il y a un algorithme un peu compliqué, mais bon c'est pas tous les jours ... 80% je fais du mapping et des boucles, et de l'affichage dans des JSP alors rien de bien méchant.

Pour ouvrir le débat, vaut-il mieux pas de commentaires ou bien des commentaires erronnés ou non mis à jour ?...

4. Le dimanche 23 mai 2010, 23:09 par Antonio Goncalves

Le pire des commentaires :

/** Retourne le nom */
public String getName() { return name;}

Trop de commentaires, tue les commentaires

5. Le lundi 24 mai 2010, 08:20 par reda

Bonjour,

Souvent je mets des commentaires sur des méthodes métiers / des algos pour garder trace de la règle métier dictée à la volée par mes collègues (Ah au fait , vous avez entendu parlé de specs ? :)

Le dernier commentaire que j'ai placé :
/**

*@Dragon 
*Méthode qui crache du feux
*Tout changement ici entrainera des conséquences graves 
*/

En gros c'était sur une méthode qui me plaçait des objets dans une hashMap avec les bons index qui vont bien , et tout mon code par la suite se basait sur cette hashMap , donc on ne devait pas tripoter cette méthode.

@++

6. Le lundi 24 mai 2010, 08:50 par Benoît Dissert

Bonjour,

En général, j'essaie de faire du code "self-explanatory", et je commente quand j'ai fait un choix.

Josh Bloch, Effective Java est aussi une bonne référence :

- commenter dans le code quand il y a besoin qu'il y ait ces commentaires pour faire la maintenance (ne pas hésiter à mettre une URL ou une référence vers un bouquin, ou les spec ...).
- la javadoc s'adresse aux utilisateurs du code, ils décrivent le contrat, il faut en particulier impérativement décrire la thread-safety d'une classe (quel contrainte est garantie, avec quel verrou s'il est public cf [Brian Goetz, Programmation concurrente en Java]).

Deux excellents exemples de javadoc cruellement mal documentée sont donnés dans le bouquin précédent de la classe SimpleDateFormat dont l'aspect non thread safe n'a pas été documenté avant une version relativement récente du JDK, ce qui fait que tout le monde imaginait que c'était thread safe, et en fait : ben non ! Autre exemple, les méthodes de récupération de connexion par JDBC, tout le monde imagine que c'est thread safe, mais en fait le contrat ne le garanti pas.

7. Le lundi 24 mai 2010, 12:47 par ChezFab

Bonjour !

Personnellement je pars du principe que le code doit être compréhensible sans commentaire (noms de classes, méthodes et variables clairs. Et il ne faut pas hésiter à mettre des noms longs (on est plus à l'époque où on doit imprimer le code) donc j'hésite pas à mettre des noms genre temporaryFlagToRememberThisValueWasTrue.

Par contre, parfois on doit faire du code uniquement pour contourner un bug ou pour résoudre un problème de communication.
Dans ce cas je mets un commentaire commençant par //!\ afin de bien rendre visible le fait que ce code n'est pas là par hasard et qu'il ne faut pas le modifier à la légère.

8. Le mardi 25 mai 2010, 08:35 par Piwaï

En un anagramme, je dirai : RTFCC !

C'est à dire... Read The Fu**ing "Clean Code" :-) .

J'ai beaucoup apprécié "Effective Java", "The Pragmatic Programmer", mais dans ce domaine je place "Clean Code" (de Uncle Bob) loin devant.

Je n'ai pas fini de lire ce bouquin, que j'ai déjà chamboulé mes pratiques... Ca aide à remettre en question les habitudes qu'on a prises, et il y a notamment une partie passionnante sur les commentaires...

Un développeur passe beaucoup beaucoup plus de temps à lire du code qu'à en écrire. Un commentaire n'est quasiment jamais à jour, intrinsèquement il ne peut pas le rester. Si vous placez des commentaires sur ce que vous estimez être du mauvais code, pour le rendre compréhensible, vous auriez bien mieux à faire à écrire des tests puis refactorer le code.

9. Le mardi 25 mai 2010, 09:24 par Corwin

Au sein de l'équipe nous utilisons des commentaires uniquement dans les méthodes de service. Le but est de mettre un commentaire d'une ligne avant chaque règle de gestion implémentée. Cette ligne contient le code de la règle (nous avons la chance d'avoir fait des specs détaillées et normalisées) ainsi que quelques mots qui reprennent l'idée de la règle. Ensuite, pas de commentaire sur la manière dont la règle est implémentée, le code parle pour lui sauf dans des cas un peu limite où, par exemple, une seul boucle sert à vérifier plusieurs règles, initialiser des éléments pour des tests postérieurs...
Le fait de remettre le code de la règle permet d'une part de valider que la règle est implémentée en un seul coup d'oeil sans même lire le code et comme que l'équipe peut changer à tout moment, il est plus facile de se positionner sur un commentaire pour commencer à investiguer que de lire toute la méthode (même courte).

10. Le mardi 25 mai 2010, 09:37 par Francois Wauquier

Hello

Ma position:
- Du code expressif, grâce à de bons choix de nommage
- Pas de commentaire de code (//)
- De la javadoc (/** ) pour les méthodes exposée public ou une API
- Si vraiment je veux mette un commentaire sur une ligne ou un bloc de code, je crée une méthode, et je met de la javadoc dessus.
- Des tests qui sont ausi de la doc

11. Le mardi 25 mai 2010, 10:13 par HollyDays

Bon, je vais éviter de redire ce qui a déjà été dit avec justesse sur «comment écrire de bons commentaires», ça n'apporterait pas grand chose.

Ceci étant dit, la question d'Anzymus, «vaut-il mieux pas de commentaires ou bien des commentaires erronés ou non mis à jour ? », est à mon sens largement aussi importante que la question de départ. Car au fond, elle y est très liée.

Je me rappelle qu'au cours de mes études d'info, un de nos profs nous avait raconté une expérience faite par, je crois me souvenir, Alcatel, sur un certain nombre de ses applications : faire une représentation extrêmement compacte montrant l'âge de chacune des lignes de code des applications, en fabriquant une image bitmap où un pixel = une ligne de code, et en fixant la couleur du pixel en fonction du temps écoulé depuis sa date de dernière modification (obtenue grâce à l'outil de source-control). Rouge pour vieux, bleu pour récent, et différentes nuances de jaune et de vert pour les intermédiaires. Simple et basique.

Résultat : les images étaient structurées en lignes ou en blocs jaunes, verts et bleus, avec quelques lignes ou blocs rouges. Mais curieusement, au milieu des blocs jaunes, verts et bleus, il y avait presque toujours plein de pixels rouges isolés (et seulement rouges). Et ces pixels rouges correspondaient systématiquement, vous l'aurez deviné... aux lignes de commentaires !

12. Le mardi 25 mai 2010, 14:04 par Florian

Bon, je vais peut-être aller à contre-courant de la plupart des commentaires, mais je pense que les commentaires sont importants ; au moins aussi importants que de faire un code simple à lire et intelligible. Je m'explique :
Pour avoir travaillé sur des applis sur lesquelles les algorithmes étaient très compliqués, je pense qu'avoir un bon commentaire explicatif et descriptif est bien mieux que de perdre une journée à lire un code. Évidemment, quand le code évolue, il faut faire évoluer le commentaire avec ! cela va de soi.

D'autre part, lorsqu'une application est très modulaire ou que nous utilisons des API externes, avoir des commentaires est plus qu'utile pour savoir ce que font les modules utilisés. Il est clair que les nom des méthodes doit être parlant, mais quand on a une méthode surchargé x fois, rien ne remplace un bon commentaire.

Enfin, je rejoins un commentaire précédent en disant qu'il faut obligatoirement documenter les limites qu'une classe a en terme de concurrence, par exemple.

13. Le mardi 25 mai 2010, 15:14 par Anzymus

Je viens d'y repenser mais il y a quelques semaines, un commentaire m'a sauvé la vie.

Contexte : Je bosse dans une cellule TMA, on maintient des projets plus ou moins activement. Et hop, on nous transmet une anomalie de production d'un projet vieux de plusieurs années : "L'exploitant avait modifié la taille d'une colonne en base, de type varchar, la passant de 10 à 20 et maintenant certaines données ne remontent plus!". Je vous passe les détails, en gros c'était une application qui utilisait Hibernate et la colonne modifiée était une clé mappée sur une classe Java un peu spéciale. On trouve la fameuse classe Java, on voit qu'effectivement il y a en dur la taille de 10 char ... mais surtout on voit le commentaire suivant :

CharArrayType - Source: http://www.hibernate.org/388.html

Rien de plus, mais ça valait tous les blablas du monde car ça nous a permis de justifier à notre client pourquoi on utilisait une méthode peu conventionnelle ... Et il n'y a rien de mieux que de justifier avec un écrit de l'éditeur du framework :-)

Donc personnellement je suis pour mettre des URL dans les commentaires ^^

14. Le mardi 25 mai 2010, 20:11 par Bruno Orsier

J'ai abordé ce sujet dans ce billet
http://blog.developpez.com/bruno-or...

Ma position : commenter quand tout le reste (nommage, simplification, refactoring) n'a pas suffit à traduire correctement l'intention du programmeur.

Bruno

15. Le mercredi 26 mai 2010, 22:13 par Olivier Croisier

Je vois que le débat fait rage :)
C'est donc qu'il y a bien un problème global, et qu'au moins certaines personnes en ont conscience. Je réfléchis à un moyen de travailler ensemble sur un "Manifeste du Commentaire", je vous en reparle sous peu.

• Comme disent Anzymus et Hollydays, de mauvais commentaires sont pires que tout. Mais pas de commentaires du tout, c'est tomber dans l'excès inverse. Il faut trouver le juste milieu, et je suis d'accord avec Florian : un petit commentaire devant chaque bloc de code homogène (j'allais dire "transactionnel") permet de scanner rapidement un code source sans perdre de temps avec les détails techniques.
• D'une manière générale, il y a un net consensus pour éliminer les commentaires des getters/setters simples (Anzymus, Antonio...). La plupart du temps ils sont générés par l'IDE, la première chose à faire est donc de modifier ce réglage.
• J'aime les idées de reda et ChezFab, qui ont chacun un système pour attirer l'attention sur des commentaires critiques. Là encore, dans les IDE il est possible d'ajouter des balises custom en plus de //TODO et //FIXME, aurant en tirer parti. J'aime bien le //!\\ :)
• reda, Corwin et Anzymus utilisent les commentaires pour rappeler les règles métier dans le code ; c'est également ma pratique, et celle des développeurs de Tomcat par exemple, qui les utilisent pour expliquer que tel bloc de code permet de prendre en compte tel cas particulier de HTTP. Mais je pense qu'il faut systématiquement les doubler avec de vériables tests unitaires, pourquoi pas avec des frameworks comme Fitnesse ou JBehave. En particulier, ce dernier permet de recueillir des "specs" à la volée, sans risque de les perdre ou d'en oublier.
• Par contre, certains ont proposé de refactorer et d'extraire le code dans de nombreuses petites méthodes bien nommées, afin d'avoir du code auto-documenté. Je ne suis pas totu à fait d'accord avec cette approche ; pour moi, si un bloc de code n'est pas destiné à être réutilisé et/ou overridé, je suis réticent à le placer dans une méthode. Cela ne me gêne pas d'avoir une méthode un peu longue, à partir du moment où elle n'exécute qu'une seule fonction logique et que sa complexité est justifiée.

Hé bien, c'était un long commentaire. Mais le débat continue :)
En particulier, il serait intéressant de faire la différence entre les commentaires inline et les commentaires javadoc.

16. Le jeudi 27 mai 2010, 00:22 par Gabriel K.

Mon avis sur la question ? No comment.
Je ... -->

17. Le jeudi 27 mai 2010, 19:02 par Florence

Perso, j'aime beaucoup le fait d'extraire des méthodes privées pour s'épargner des commentaires. Cela permet d'avoir toujours une description à jour et de s'épargner de rentrer dans le détail si ce n'est pas ce qui nous intéresse (donc plus de lisibilité).

Quant aux commentaires type TODO/FIXME pour signaler quelque chose de critique, j'en ai mis mais je suis rarement revenue dessus, et encore moi un autre membre de l'équipe. Ils polluent juste un peu plus le code de jour en jour.

Je faisais très attention à mettre à jour mes commentaires. Concrètement ça donnait : un test unitaire, l'implémentation, mise à jour du commentaire, un autre test U, implémentation, MAJ du commentaire, et c'était vraiment redondant. Malgré tout, les autres devs devaient regarder le code malgré tout, "au cas ou" mon commentaire n'était pas à jour. S'il faut de toute facon regarder le code, autant ne pas en faire.

Et pourtant, j'en mets, un peu. Yen a suffisamment peu pour que je puisse espérer qu'ils soient lus. En plus des règles métiers, il y a aussi la gestion des cas particuliers (@throws XXException when XX). Ce serait trop long à expliquer dans le nom d'une méthode. Finalement, les commentaires se justifient quand "ça ne tient pas dans la méthode". Autre cas : expliquer quelque chose de très bizarre, si je n'arrive pas à faire autrement et ainsi éviter qu'un mec derriere le vire parce que cela ne se justifie pas pour lui (quoique.... dans ce cas, je ferai souvent mieux de mettre un test U avec). Enfin : pour une API et des classes utilitaires, afin d'éviter aux développeurs de devoir rentrer dans le code pour savoir ce qui est fait.

18. Le vendredi 28 mai 2010, 07:09 par Daniel Chaffiol

Encore merci pour cet intéressant débat hier au KawaCampParis2 (http://barcamp.org/KawaCampParis2).

J'avais posté une question liée à ce sujet sur Stack Overflow il y a quelque temps: "api documentation and “value limits”: do they match ?" (http://stackoverflow.com/questions/...).

Sinon, il y a pleins d'autres réponses sur ce sujet, toujours sur Stack Overflow: http://stackoverflow.com/questions/...
Cela inclue l'humoristique "What’s the least useful comment you’ve ever seen?" (http://stackoverflow.com/questions/...), avec mon favori:

//@TODO: Rewrite this, it sucks. Seriously.

19. Le vendredi 28 mai 2010, 09:46 par Pierre-Jean

De mon côté, j'essaie d'écrire le moins possible de code car ça nuit à la relecture de deux manières :

• augmentation considérable du nombres de lignes dans certains cas,
• moins j'écris de commentaires dans le code, plus ce dernier est compréhensible à la première lecture.

Concernant la javadoc, je me limite à une phrase simple pour expliquer les méthodes publiques et je rajoute le détail des pré et post conditions. C'est, pour moi, l'essentiel pour un développeur utilisant mon API.

Concernant les commentaires, moins j'en écris, plus je suis satisfait de mon code. En général, si je mets un commentaire du style "Pourquoi je fais telle instruction", c'est souvent signe qu'à la lecture, ce n'est pas intuitif et donc que mon code n'est pas propre (Exemple : rajouter un flag ou je ne sais quoi à l'arrache...) ou trop complexe.

Enfin, concernant les commentaires du type "Comment...", je les réserve pour les algos qui prennent de la place et que je ne peux/veux pas découper en plusieurs méthodes. Mais çà reste rare.

Au final, le commentaire est vraiment le dernier palier permettant d'expliquer ce que fait telle classe/méthode mais en aucun cas un outils permettant de faire de la redondance quand la lecture du code est suffisamment claire.

20. Le vendredi 28 mai 2010, 19:17 par Daniel Chaffiol

Pour ajouter à mon précédent commentaire: comment bénéficier d'une "javadoc étendue" directement (et automatiquement) extraite du code sous Eclipse? : http://code-recommenders.blogspot.c...