Inscrivez-vous gratuitement
pour pouvoir participer, suivre les réponses en temps réel, voter pour les messages, poser vos propres questions et recevoir la newsletter
Discussion :
J'aime bien lire ce genre d'article. Ça me rappelle à qu'elle point une architecture propre et logique facilite la maintenance (parce que le mec connait le système pour lequel il code) autant que les commentaires. Dans ce cas, ce genre d'article est tout à fait pertinent.
Sinon le challenge c'est de comprendre l’esprit tordu qui à écrit le code, et les commentaires que vous trouverez dedans seront tout aussi tordu et dénué de sens et ne vous aiderons pas beaucoup plus.
Dernière modification par Invité ; 19/07/2017 à 21h18. Motif: Typo
Les variables sont très bien nommées, le code en lui même n'est pas forcement complexe, mais le système l'est.Envoyé par martopioche
De par cela le code le devient car pour faire la moindre chose il y a des interconnexions avec d'autres modules voir d'autres composants électronique.
Rajoutes de l'asynchronisme et du temps réel dedans et tu obtiens un sacré beau bordel pour un non initié.
Quand je suis arrivé sur le projet j'ai mis un mois pour corriger le premier ticket ouvert qu'on m'a attribué...
Bon nombre de bug nécessitent 3-4 jours de lecture et de tests pour finalement rajouter une condition. Je t'explique pas à combien tourne notre indicateur de temps passé / ligne de code.
De plus la quantité de code rend les choses difficilement mémorisable, on se souvient peu de la partie qu'on a débuggué il y a 2ans...
Le code est tellement gros qu'une équipe de dix personnes peut passer 3ans sans intervenir sur un module... Du coup quand on s'y replonge c'est pas simple. Tout commentaire est bon à prendre pour se balader dedans.
« Toujours se souvenir que la majorité des ennuis viennent de l'espace occupé entre la chaise et l'écran de l'ordinateur. »
« Le watchdog aboie, les tests passent »
Les enseignants en pensent quoi ?
Et vous ?
À quelle fréquence pensez-vous utiliser des commentaires ? Rarement, souvent, très souvent ?
J'ai plus eu des conseils, sachant que très souvent la modélisation comportait déjà les commentaires.
Quelques rares fois, il était obligatoire de mettre quelques "repères" supplémentaires lors de l'implémentation. Surtout lors de la découverte par la pratique de framework ou librairies. Mais en aucun cas ces commentaires seraient utiles hors de la phase d'apprentissage.
Surement pour un algorithme très tordu... Comme afficher une formule mathématique en HTML avec un clavier qui ne connait pas i de C...
Dernière modification par MikeRowSoft ; 19/07/2017 à 16h46.
On a tous été débutant, et la plupart de mes stagiaires n'ont jamais entendu parler des architectures trois tiers, par exemple. Là, j'ai un stagiaire qui connait bien Angular + Typescript mais pas du tout Java + Spring. J'estime que je ne fais pas mon boulot de maître de stage si je le fais travailler exclusivement sur le front end.
Peut être que ça nécessiterait un peu de refactoring dans ce cas. Des tâches trop complexes peuvent toujours être divisées en un ensemble de tâches plus simples.
Développeur / Formateur
Tutoriels AngularJS / Node.js sur ma chaîne Youtube : http://www.youtube.com/user/DevDuFutur
Et ça c'est ce que l'on trouve systématiquement sur le code qui a évolué pendant des années, qui a grossi et qui malheureusement est un gros monolithe. Je connais, extraire un webservice nous a demandé 3 jours avec en pair avec un expert… Ce qui manque certainement actuellement c'est une réorganisation, une révision de l'architecture que personne ne fera pour éviter de réparer les choses qui marchent…De par cela le code le devient car pour faire la moindre chose il y a des interconnexions avec d'autres modules voir d'autres composants électronique.
Rajoutes de l'asynchronisme et du temps réel dedans et tu obtiens un sacré beau bordel pour un non initié.
De plus la quantité de code rend les choses difficilement mémorisable, on se souvient peu de la partie qu'on a débuggué il y a 2ans...
Le code est tellement gros qu'une équipe de dix personnes peut passer 3ans sans intervenir sur un module... Du coup quand on s'y replonge c'est pas simple. Tout commentaire est bon à prendre pour se balader dedans.
Un stagiaire est pire qu'un débutant : c'est un étudiant. Par définition, il n'a pas la compétence d'un "développeur" (je met des guillemets car ça dépend de votre descriptif de poste…), même débutant. On ne met pas un stagiaire sur un ticket si on ne l'a pas formé sur le coté technique sur lequel on le met. Oui parce que le "boulot de maître de stage", c'est aussi la formation du stagiaire.
Donc tu ne fait que confirmer l'erreur de staffing.
J'adore vos réactions tellement prévisibles...
Si c'est complexe c'est forcement que le code est bon à refactoriser...
Allez bosser sur des gros logiciels embarqués une fois dans votre vie et on en reparlera je pense.
Je ne vois pas comparer un webservice avec le système de guidage d'un missile ou bien le système de communication d'une navette spatiale.
Même correctement factorisé un logiciel de plusieurs centaine de millier de lignes reste en partie obscur dans la plupart de son fonctionnement au meilleur expert de la terre.
Pas le temps de potasser le tout qu'il y a déjà de nouvelles améliorations à apporter.
« Toujours se souvenir que la majorité des ennuis viennent de l'espace occupé entre la chaise et l'écran de l'ordinateur. »
« Le watchdog aboie, les tests passent »
Tu as bien compris le problème de relecture du code source sans ihm.
RAD Studio est surement l'EDI qui facilite le plus la relecture. Une thread peut avoir un composant sur une ihm... (vieux souvenir de C++ Builder)
C'est exactement ce que j'ai conclu…
L'inconvénient des commentaires, c'est de risquer de ne pas être à jour par rapport au code.
En particulier, quand le code est mis à jour par des développeurs trop pressés, on peut se retrouver avec des absurdités du style :
qui peuvent être évitées avec une variable intermédiaire :
Code : Sélectionner tout - Visualiser dans une fenêtre à part Sleep(3000); // Attendre 2 secondes.
Code : Sélectionner tout - Visualiser dans une fenêtre à part
2
Il est pertinent de créer une sous-fonction dans les deux cas suivants :
- La sous-fonction est appelée dans plusieurs fonctions différentes. On évite alors les copiés-collés.
- La fonction appelante devient trop grosse. Pour qu'on puisse la comprendre facilement de manière globale, il faut déplacer une partie de son code dans des sous-fonctions avec un nom parlant.
Cela dit, si une fonction de taille modeste contient un ou deux bouts de code que je souhaite commenter et que ces bouts de code n'existent pas ailleurs, je ne vais pas les transformer en sous-fonctions seulement pour éviter d'écrire des commentaires !
L'inconvénient de morceler en sous-fonctions, c'est qu'il faut faire des aller-retours dans le code si on veut voir l'implémentation de ces sous-fonctions.
Je suis d'accord.
Faire du défensif ne sert pas à éviter les commentaires, mais à détecter les erreurs à l'exécution.
Cependant, puisqu'une instruction telle que checkArgument(height > 0); indique déjà clairement la précondition de la fonction, il est inutile de rappeler en plus cette précondition sous la forme d'un commentaire.
J'écris des commentaires dans les cas suivants :
- Expliquer un choix, surtout s'il paraît étrange à un lecteur qui ne connaît pas le contexte.
- Résumer en quelques mots ce que fait une fonction ou ce que représente une classe, sauf si le nom de la fonction ou de la classe est déjà un résumé satisfaisant.
Le rôle du résumé est d'éviter d'obliger le lecteur à plonger dans le code s'il a besoin d'une information plus précise que le nom de la fonction ou de la classe mais pas forcément aussi précise que le code.
De même, il m'arrive parfois de résumer sous forme de commentaire ce que fait un bloc de code dans les cas où il n'est pas pertinent de déplacer ce bloc de code dans une sous-fonction (voir ci-avant).- Avertir sur les dangers d'une certaine fonction ou classe. Exemple : Attention, le bogue machin du ticket n°XXXX n'a pas encore été corrigé.
- Écrire parfois quelques "rappels" techniques si le lecteur a des chances de ne pas les avoir. Cela rejoint d'une certaine manière ce que disait BugFactory, mais ça ne s'applique pas qu'aux stagiaires. Cela s'applique aussi si on fait appel à des subtilités d'un langage ou d'une bibliothèque. Par exemple, en C++, il m'arrive d'écrire un commentaire du genre :
Code : Sélectionner tout - Visualiser dans une fenêtre à part
2
3
4// Rappel : propriétés de l'initialisation d'une variable locale statique : // - Si l'initialisation lance une exception, elle est considérée comme non faite et // sera retentée au prochain passage. // - L'initialisation est thread-safe depuis C++11.- Mettre en évidence qu'un certain détail d'implémentation ne fait pas partie de l'interface.
Par exemple, dans une certaine classe, l'implémentation actuelle utilise un certain type de tableau associatif sous forme d'arbre binaire de recherche qui trie les éléments dans l'ordre des clés, mais l'implémentation future pourrait utiliser une table de hashage sans ce tri. Alors, dans l'interface de la classe, il vaut mieux avertir sous forme de commentaire : attention, ne vous reposez pas sur l'hypothèse que les éléments sont triés dans l'ordre des clés, car ça pourrait changer plus tard.- Aider l'utilisateur qui explore le code avec des commentaires de type "voir aussi telle fonction ou telle classe". Par exemple, quand il y a plusieurs fonction similaires (mais différentes), ce genre de commentaire aide l'utilisateur à trouver la bonne fonction à appeler.
Cela dit, comme je l'ai précisé, je suis conscient que, l'inconvénient des commentaires, c'est de risquer de ne pas être à jour par rapport au code. Du coup, quand une fonction a un code très simple et très petit, je préfère que la doc soit le code.
Par exemple, en C++, pour éviter d'écrire certaines préconditions et post-conditions sous forme de commentaires, il m'arrive de créer des fonctions en ligne qui ressemblent à :
et, pour décrire les invariants d'une classe, il m'arrive de créer une fonction membre :
Code : Sélectionner tout - Visualiser dans une fenêtre à part
2
3
4
5
6
7double my_sqrt(double param) { assert(param >= 0); double result = my_sqrt_impl(param); assert(result >= 0); return result; } // Rq : Dans du vrai code, je ne réimplémente pas sqrt, mais c'est pour l'exemple.
Du coup, je configure l'outil de génération de code (dans mon cas, Doxygen) pour afficher aussi le code des fonctions. L'inconvénient est que l'ensemble des fichiers générés pour la documentation est assez volumineux.
Code : Sélectionner tout - Visualiser dans une fenêtre à part
2
3bool invariant() const { // code qui retourne true si les invariants de la classe sont respectés }
Ta liste est bien, mais j'en rajoute 3 autres
- Faire des commentaires pour faire des points d’ancrage lors d'un bloc très long
Par exemple, en C++, lors de la déclaration d'une classe j'utilise les commentaires "// Constructors", "// Constructors & Destructors", "// Public Interface", "// Private Interface", "// Attributes".
Ou bien un long traitement: les commentaires permettent de faire des "titres de section"- Pour expliquer concisément un algo que j'ai trouvé sur Internet, souvent en y joignant une URL même si elle est périssable.
Par exemple, une requête SQL qui permet de récupérer le premier id non utilisé (pour remplir les trous) ou bien le calcul de couleur d'une surface transparente au dessus d'une autre surface.- Pour laisser du code mort. Par exemple un test qu'on a retiré parce qu'il [est/ semble] inutile, mais on le laisse en commentaire au cas où, ou alors un bout de code qu'on a réimplémenté.
- Bonus un petit "// <- XXX" pour préciser tout le code qui doit être supprimé dans le code final. Ce commentaire n'est pas nécessaire ni suffisant, mais au moins ce code peut-être est supprimé sans trop de réflexion lors de la relecture finale/ tests finaux
Et j'aime bien la pseudo-convention XXX, même si je ne mets que des XXX TODO
J'hésite entre :
- vous ne connaissez pas les IDEs ? Outils super pratiques qui permettent en général de naviguer dans le code
et
- pourquoi voir l'implémentation ? Si vous trouvez en Python print() ou en Java System.out.println() (ou l'équivalent dans d'autres langages), avez vous l'envie de voir l'implémentation ? Donc pourquoi y aller pour filterOffensiveWords() ?
N'est-ce pas plutôt de la documentation que du commentaire ça ?Résumer en quelques mots ce que fait une fonction ou ce que représente une classe, sauf si le nom de la fonction ou de la classe est déjà un résumé satisfaisant.
Le rôle du résumé est d'éviter d'obliger le lecteur à plonger dans le code s'il a besoin d'une information plus précise que le nom de la fonction ou de la classe mais pas forcément aussi précise que le code.
Auparavant, tu écris toi même :Avertir sur les dangers d'une certaine fonction ou classe. Exemple : Attention, le bogue machin du ticket n°XXXX n'a pas encore été corrigé.
Quand le ticket sera corrigé, qui ira mettre à jour les commentaires ? Quand quelqu'un relira cette partie, qui ira vérifier si le ticket a été fermé ?L'inconvénient des commentaires, c'est de risquer de ne pas être à jour par rapport au code.
Et là aussi, le commentaire sert à compenser une erreur de staffing…Écrire parfois quelques "rappels" techniques si le lecteur a des chances de ne pas les avoir. Cela rejoint d'une certaine manière ce que disait BugFactory, mais ça ne s'applique pas qu'aux stagiaires. Cela s'applique aussi si on fait appel à des subtilités d'un langage ou d'une bibliothèque.
Là je cite l'exemple car en lui même il concerne quelque chose qui relève de la documentation.Mettre en évidence qu'un certain détail d'implémentation ne fait pas partie de l'interface.
Par exemple, dans une certaine classe, l'implémentation actuelle utilise un certain type de tableau associatif sous forme d'arbre binaire de recherche qui trie les éléments dans l'ordre des clés, mais l'implémentation future pourrait utiliser une table de hashage sans ce tri. Alors, dans l'interface de la classe, il vaut mieux avertir sous forme de commentaire : attention, ne vous reposez pas sur l'hypothèse que les éléments sont triés dans l'ordre des clés, car ça pourrait changer plus tard.
Cette information là n'a pas sa place dans un commentaire mais la documentation.Aider l'utilisateur qui explore le code avec des commentaires de type "voir aussi telle fonction ou telle classe". Par exemple, quand il y a plusieurs fonction similaires (mais différentes), ce genre de commentaire aide l'utilisateur à trouver la bonne fonction à appeler.
Punaise, c'est si obsolète que ça les IDEs en C++ ???
Au cas où quoi ? Qui va décommenter du "code mort" ??? Je ne connais aucun dev qui ira vérifier si un "code mort" peut servir de test plutôt que l'écrire lui même. Un dev qui met // devant du code s'est juste planté de touches, il voulait faire shift+flêche bas puis delete.Pour laisser du code mort. Par exemple un test qu'on a retiré parce qu'il [est/ semble] inutile, mais on le laisse en commentaire au cas où, ou alors un bout de code qu'on a réimplémenté.
Gné ??? C'est quoi le "code final" ?Bonus un petit "// <- XXX" pour préciser tout le code qui doit être supprimé dans le code final. Ce commentaire n'est pas nécessaire ni suffisant, mais au moins ce code peut-être est supprimé sans trop de réflexion lors de la relecture finale/ tests finaux
Oui mais la documentation n'est-elle pas générée à partir des commentaires ? Qui de l’œuf de la poule ?
Et aussi, qui va lire une documentation technique de ton code (et non pas la documentation d'une bibliothèque)
Mettre l'information au plus près n'est pas plus mauvais que la mettre à l’extérieur et que personne ne la voit/ ne la trouve
Le problème de synchronisation est valable pour les 2 cas.
Oui martopioche, nous avons tous bien compris que c'est toi le meilleur... et que ceux qui écrivent du code procédural sont des porcs.
Anecdote personnelle au sujet des commentaires :
J'avais une fonction qui était objectivement dégueulasse... ce qu'elle faisait était tellement compliqué que je n'arrivais pas à voir comment l'écrire autrement sans au minimum risquer de perdre encore plus de temps pour débugger la nouvelle version plus propre que j'en avais mis pour débugger la première...
Alors je l'ai laissée, mais j'ai quand même ajouté des commentaires, non pour expliquer ce que faisait le code (il était déjà très clair notamment parce qu'il appliquait certains des conseils donnés par Monsieur Google, ou par des intervenants de ce fil de discussion), mais parce que la chose faite était en elle-même compliquée...
Du moins c'est ce que je croyais... je sentais qu'il allait falloir réécrire tout ça en mieux... mais je laissais ainsi parce que je n'étais pas sûr d'avoir déjà le recul pour faire suffisamment mieux d'un coup...
Quelques jours plus tard j'ai du ajouter un cas dans cette fonction à la noix.
Ce cas a entraîné un nouveau bug... et j'ai voulu débogger... sauf que la fonction était si affreuse que même la recherche de la cause du plantage devenait douloureuse pour moi, alors que j'adore le débuggage en temps normal (pour moi c'est un peu une science expérimentale :-)
C'est ce détail qui m'a décidé à réécrire la fonction mieux. Mais "mieux", ce n'était pas une question d'avoir un code plus lisible ou plus factorisé au sens où on l'entend habituellement...
J'ai carrément changé l'algo et l'approche.... et j'ai obtenu un truc sans bug et tellement limpide comparé à la première version que j'ai vu que même mon commentaire qui m'avait paru nécessaire ne servait plus à rien. C'est avec un grand bonheur que je l'ai supprimé.
Dans l'écriture du code, avec l'expérience je constate que la quantité de commentaires que j'écris reste à peu près constante, parce que :
- d'un côté plus le code est amélioré, plus certains types de commentaires peuvent et doivent disparaitre ;
- d'un autre côté il y a des cas où je n'aurais pas eu l'idée de mettre des commentaires dans le passé mais où cela me semble pertinent maintenant (exemple : "attention dans cette fonction, il serait tentant de modifier telle chose, mais en fait ce n'est pas une bonne idée pour telle raison, etc.")
D'une part, quand je fais une comparaison de code entre deux révisions SVN, le code n'est pas ouvert dans un IDE.
D'autre part, même avec un vrai IDE, rien n'est plus rapide qu'avoir directement le code sur place, sous les yeux.
Par exemple, cela peut arriver si la documentation technique ne précise pas sur quel critère le programme se base pour déterminer si un mot est injurieux voire ne précise pas que le programme filtre les mots injurieux.
Scénario possible : Un client se plaint qu'un certain mot ne soit pas pris en compte. Le help desk ne reproduit pas le problème en local et me le retransmet. Je découvre que le code appelle filterOffensiveWords() et je soupçonne cette fonction d'avoir filtré le mot chez le client mais pas chez moi. J'ai besoin de savoir comment elle marche. Je lis son code et je découvre que la liste des mots injurieux se base, entre autres, sur un fichier de préférences du client. Je complète alors des documentations dont celle destinée au help desk pour que, la prochaine fois, le personnel du help desk regarde dans le fichier de préférence du client avant de me retransmettre le problème.
Personnellement, quand j'écris un commentaire relatif à un ticket, je complète le ticket et j'y écrit "Voir les occurrences de XXXX (le numéro du ticket) dans le code". Du coup, il y a un léger espoir que celui qui aura corrigé le ticket mettra à jour le commentaire.
Sinon, si le commentaire n'a pas été mis à jour et que quelqu'un le lit, il se peut qu'il cherche à avoir plus d'informations en consultant le ticket puis découvre que le ticket est fermé. Alors, il devrait supprimer le commentaire.
On dirait que je fais pareil que foetus.
Parfois, lors d'un développement, j'ai besoin d'avoir sous les yeux comment étaient certaines portions de code juste avant que je ne les modifie, sans perdre du temps à chercher la précédente version dans la dernière révision SVN. Alors, au lieu de supprimer tout de suite l'ancienne portion de code, je la mets en commentaires. Quand le développement est fini et qu'il semble bien marcher, je supprime le code mort avant le commit.
Pas de commentaire
Bonjour
Très intéressant de relancer le débat.
Il est encore bien courant pour des enseignants de transmettre l'une des plus grandes erreurs selon moi : commenter son code.
Commenter son code, c'est permettre qu'il ne soit pas lisible.
C'est pourquoi dans mon entreprise, j'ai interdit les commentaires de code, avec deux exceptions :
- les commentaires publics (commentaires de méthodes, pour la doc auto-générée)
- les commentaires sur un code non améliorable (exemple, dans une procédure stockée, où la lisibilité du code peut empêcher l'optimisation d'une requête)
C'est un très bon principe et je pense qu'il faut l'enseigner à tout le monde.
A bientôt
Evan
Cela peut paraître à de la micro optimisation, mais c'est un code en retirant définitivement:
- Tous les debugs qui ne peuvent pas être désactivés et très souvent codés/ rajoutés à l'arrache.
- Tous les "fake", "stub", ou autres "test double" qui ne servent plus à rien.
Et même des fois, tu les as retirés (en cours de développement) mais il reste des initialisations seule/ des "include" par exemple que tu avais loupé (c'est pour cela que j'utilise un commentaire "// <- XXX" pour les marquer).
Oui et non, documentation et commentaires sont deux choses différentes pour deux lecteurs différents, le problème est que qu'il manque un mot entre "documenter le code" de manière générale et la documentation qui n'est pas un commentaire :Oui mais la documentation n'est-elle pas générée à partir des commentaires ? Qui de l’œuf de la poule ?
Et aussi, qui va lire une documentation technique de ton code (et non pas la documentation d'une bibliothèque)
Un commentaire, c'est tout ce que tu a dans le code et qui commence par un // ou un # (en fonction du langage) et qui se trouve n'importe où dans le code. La documentation, c'est tout ces blocs spéciaux extraits par les outils comme Javadoc, Doxygen, Pydoc… et qui permettent de générer la documentation, mais qui sont également reconnus par les IDEs en tant que tel. Les premiers sont destinés aux devs qui interviennent sur le code, l'utilisateur des fonctions/classes/modules/libs (peu importe le nom) n'en n'a rien à faire car il ne les verra pas (il n'a pas à aller "étudier le code" pour comprendre comment il fonctionne). Les seconds sont destinés aux utilisateurs des fonctions/classes/modules/libs et donc l'informent sur l'usage des fonctions/classes/modules/libs.
Ici, tout ce qui est présenté concerne les commentaires, pas dans la documentation, ce qui est présenté dans OP n'a rien à faire dans une documentation, c'est à dire à destination des utilisateurs des fonctions/classes/modules/libs.
Et donc justement, un commentaire est au plus près de ce qu'il explique, ce qui relève de la documentation est imposé par les langages (Javadoc /** */ au dessus des fonctions/classes…, Pydoc """ """ en dessous…) mais facilement exploitable avec les outils liés aux langages (documentation générée, IDEs, help() pour Python…).Mettre l'information au plus près n'est pas plus mauvais que la mettre à l’extérieur et que personne ne la voit/ ne la trouve
Le problème de synchronisation est valable pour les 2 cas.
Merci pour le sophisme, mais en ce qui me concerne, je ne parle pas de moi et ne généralise pas mes anecdotes, pratiques courantes sur les forums. Je cite des pratiques qui font consensus et ont fait leurs preuves. Ça ira mieux si je te dirige vers des ouvrages comme Clean Code de Robert Martin ?
Vous avez un bloqueur de publicités installé.
Le Club Developpez.com n'affiche que des publicités IT, discrètes et non intrusives.
Afin que nous puissions continuer à vous fournir gratuitement du contenu de qualité, merci de nous soutenir en désactivant votre bloqueur de publicités sur Developpez.com.
Répondre avec citation
Partager