+ Répondre à la discussion Actualité déjà publiée
Page 2 sur 8 PremièrePremière 123456 ... DernièreDernière
  1. #21
    Nouveau membre du Club
    Homme Profil pro
    Développeur Java
    Inscrit en
    novembre 2014
    Messages
    23
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 32
    Localisation : France, Paris (Île de France)

    Informations professionnelles :
    Activité : Développeur Java

    Informations forums :
    Inscription : novembre 2014
    Messages : 23
    Points : 34
    Points
    34

    Par défaut

    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.

  2. #22
    Expert éminent
    Avatar de transgohan
    Homme Profil pro
    Développeur Temps réel Embarqué
    Inscrit en
    janvier 2011
    Messages
    2 318
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Maine et Loire (Pays de la Loire)

    Informations professionnelles :
    Activité : Développeur Temps réel Embarqué

    Informations forums :
    Inscription : janvier 2011
    Messages : 2 318
    Points : 6 393
    Points
    6 393

    Par défaut

    Citation Envoyé par martopioche Voir le message
    Peut-être justement parce qu'il est maintenu dans un état "complexe"… D'expérience, ce type de remarque concerne toujours du code où on ne comprends rien aux noms des variables, où tout est écrit de manière procédurale et la compréhension nécessite de lire chaque ligne. Le bon sens présenté ici est de remettre en évidence que fonctions et variables ont des noms et que du code peut être déporté dans une fonction pour en expliquer l'intention.
    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.
    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.

  3. #23
    Provisoirement toléré Avatar de MikeRowSoft
    Homme Profil pro
    sans profession ou en recherche d'emploi
    Inscrit en
    avril 2013
    Messages
    1 295
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 39
    Localisation : France, Puy de Dôme (Auvergne)

    Informations professionnelles :
    Activité : sans profession ou en recherche d'emploi

    Informations forums :
    Inscription : avril 2013
    Messages : 1 295
    Points : 160
    Points
    160

    Par défaut

    Citation Envoyé par Michael Guilloux Voir le message

    Et vous ?

    À quelle fréquence pensez-vous utiliser des commentaires ? Rarement, souvent, très souvent ?
    Quelles règles observez-vous pour insérer des commentaires dans votre code ?
    Les enseignants en pensent quoi ?

    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.

    Citation Envoyé par Michael Guilloux Voir le message

    Quelles règles observez-vous pour insérer des commentaires dans votre code ?
    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...

  4. #24
    Membre éprouvé
    Profil pro
    Inscrit en
    octobre 2005
    Messages
    845
    Détails du profil
    Informations personnelles :
    Âge : 37
    Localisation : France

    Informations forums :
    Inscription : octobre 2005
    Messages : 845
    Points : 1 281
    Points
    1 281

    Par défaut

    Citation Envoyé par martopioche Voir le message
    Si il y a saccage d'une architecture du fait d'un ticket, j'appelle ça une erreur de staffing…
    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.

  5. #25
    Membre actif
    Inscrit en
    novembre 2006
    Messages
    100
    Détails du profil
    Informations forums :
    Inscription : novembre 2006
    Messages : 100
    Points : 216
    Points
    216

    Par défaut

    Citation Envoyé par transgohan Voir le message
    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.
    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.
    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

  6. #26
    Membre confirmé
    Profil pro
    Inscrit en
    décembre 2006
    Messages
    607
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : décembre 2006
    Messages : 607
    Points : 640
    Points
    640

    Par défaut

    Citation Envoyé par transgohan Voir le message
    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.
    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…

    Citation Envoyé par BugFactory Voir le message
    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.
    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.

  7. #27
    Expert éminent
    Avatar de transgohan
    Homme Profil pro
    Développeur Temps réel Embarqué
    Inscrit en
    janvier 2011
    Messages
    2 318
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Maine et Loire (Pays de la Loire)

    Informations professionnelles :
    Activité : Développeur Temps réel Embarqué

    Informations forums :
    Inscription : janvier 2011
    Messages : 2 318
    Points : 6 393
    Points
    6 393

    Par défaut

    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.

  8. #28
    Provisoirement toléré Avatar de MikeRowSoft
    Homme Profil pro
    sans profession ou en recherche d'emploi
    Inscrit en
    avril 2013
    Messages
    1 295
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 39
    Localisation : France, Puy de Dôme (Auvergne)

    Informations professionnelles :
    Activité : sans profession ou en recherche d'emploi

    Informations forums :
    Inscription : avril 2013
    Messages : 1 295
    Points : 160
    Points
    160

    Par défaut

    Citation Envoyé par transgohan Voir le message
    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.
    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)

  9. #29
    Membre confirmé
    Profil pro
    Inscrit en
    décembre 2006
    Messages
    607
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : décembre 2006
    Messages : 607
    Points : 640
    Points
    640

    Par défaut

    Citation Envoyé par transgohan Voir le message
    Pas le temps de potasser le tout qu'il y a déjà de nouvelles améliorations à apporter.
    C'est exactement ce que j'ai conclu…

  10. #30
    Membre chevronné
    Avatar de Pyramidev
    Homme Profil pro
    Développeur
    Inscrit en
    avril 2016
    Messages
    469
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Val de Marne (Île de France)

    Informations professionnelles :
    Activité : Développeur

    Informations forums :
    Inscription : avril 2016
    Messages : 469
    Points : 2 080
    Points
    2 080

    Par défaut

    Citation Envoyé par jopopmk Voir le message
    1. Introduire une variable explicative
    Non, je vais pas rajouter une variable inutile.
    Si vraiment on a besoin d'une explication alors un commentaire va très bien.
    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 :
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    Sleep(3000); // Attendre 2 secondes.
    qui peuvent être évitées avec une variable intermédiaire :
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    const DWORD durationMilliseconds = 3000;
    Sleep(durationMilliseconds);
    Citation Envoyé par jopopmk Voir le message
    2. Extraire une méthode
    Toujours non, je vais pas empiler des appels inutiles.
    Si vraiment on a besoin d'une explication alors un commentaire va très bien.
    Nous sommes peut-être d'accord.
    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.

    Citation Envoyé par jopopmk Voir le message
    3. Utiliser un nom d'identificateur plus descriptif
    Là c'est assez évident. Maintenant il peut arriver qu'on se retrouve avec des noms sans fin, on peut alors contextualiser les variables avec un petit commentaire (dans l'exemple, en tête d'algo, indiquer "all sizes in pixels" ).
    Je suis d'accord.

    Citation Envoyé par jopopmk Voir le message
    4. Ajouter un contrôle dans le cas où votre code a des hypothèses
    Gné ? Faire du défensif pour économiser un commentaire ? Là je sais même pas quoi dire ...
    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.

    Citation Envoyé par Michael Guilloux Voir le message
    Quelles règles observez-vous pour insérer des commentaires dans votre code ?
    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
      1
      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 à :
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    7
    double 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.
    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
    1
    2
    3
    bool invariant() const {
        // code qui retourne true si les invariants de la classe sont respectés
    }
    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.

  11. #31
    Expert confirmé
    Homme Profil pro
    Analyste/ Programmeur
    Inscrit en
    juillet 2013
    Messages
    2 200
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Bouches du Rhône (Provence Alpes Côte d'Azur)

    Informations professionnelles :
    Activité : Analyste/ Programmeur

    Informations forums :
    Inscription : juillet 2013
    Messages : 2 200
    Points : 4 878
    Points
    4 878

    Par défaut

    Citation Envoyé par Pyramidev Voir le message
    J'écris des commentaires dans les cas suivants :
    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

  12. #32
    Membre confirmé
    Profil pro
    Inscrit en
    décembre 2006
    Messages
    607
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : décembre 2006
    Messages : 607
    Points : 640
    Points
    640

    Par défaut

    Citation Envoyé par Pyramidev Voir le message
    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.
    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() ?

    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.
    N'est-ce pas plutôt de la documentation que du commentaire ça ?

    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é.
    Auparavant, tu écris toi même :
    L'inconvénient des commentaires, c'est de risquer de ne pas être à jour par rapport au code.
    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é ?

    É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.
    Et là aussi, le commentaire sert à compenser une erreur de staffing…

    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.
    Là je cite l'exemple car en lui même il concerne quelque chose qui relève de 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.
    Cette information là n'a pas sa place dans un commentaire mais la documentation.

  13. #33
    Membre confirmé
    Profil pro
    Inscrit en
    décembre 2006
    Messages
    607
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : décembre 2006
    Messages : 607
    Points : 640
    Points
    640

    Par défaut

    Citation Envoyé par foetus Voir le message
    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"
    Punaise, c'est si obsolète que ça les IDEs en C++ ???

    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é.
    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.

    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
    Gné ??? C'est quoi le "code final" ?

  14. #34
    Expert confirmé
    Homme Profil pro
    Analyste/ Programmeur
    Inscrit en
    juillet 2013
    Messages
    2 200
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Bouches du Rhône (Provence Alpes Côte d'Azur)

    Informations professionnelles :
    Activité : Analyste/ Programmeur

    Informations forums :
    Inscription : juillet 2013
    Messages : 2 200
    Points : 4 878
    Points
    4 878

    Par défaut

    Citation Envoyé par martopioche Voir le message
    Et là aussi, le commentaire sert à compenser une erreur de staffing…
    Là je cite l'exemple car en lui même il concerne quelque chose qui relève de la documentation.
    Cette information là n'a pas sa place dans un commentaire mais la documentation.
    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.

  15. #35
    En attente de confirmation mail

    Profil pro
    Inscrit en
    septembre 2013
    Messages
    642
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : septembre 2013
    Messages : 642
    Points : 2 280
    Points
    2 280

    Par défaut

    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.")

  16. #36
    Membre chevronné
    Avatar de Pyramidev
    Homme Profil pro
    Développeur
    Inscrit en
    avril 2016
    Messages
    469
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Val de Marne (Île de France)

    Informations professionnelles :
    Activité : Développeur

    Informations forums :
    Inscription : avril 2016
    Messages : 469
    Points : 2 080
    Points
    2 080

    Par défaut

    Citation Envoyé par martopioche Voir le message
    - vous ne connaissez pas les IDEs ? Outils super pratiques qui permettent en général de naviguer dans le code
    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.

    Citation Envoyé par martopioche Voir le message
    - 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() ?
    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.

    Citation Envoyé par martopioche Voir le message
    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é ?
    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.

    Citation Envoyé par foetus Voir le message
    • 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
    Citation Envoyé par martopioche Voir le message
    Au cas où quoi ? Qui va décommenter du "code mort" ???
    Citation Envoyé par martopioche Voir le message
    Gné ??? C'est quoi le "code final" ?
    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.

  17. #37
    Membre à l'essai
    Homme Profil pro
    Formateur en informatique
    Inscrit en
    juillet 2017
    Messages
    8
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Loire Atlantique (Pays de la Loire)

    Informations professionnelles :
    Activité : Formateur en informatique

    Informations forums :
    Inscription : juillet 2017
    Messages : 8
    Points : 12
    Points
    12

    Par défaut 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

  18. #38
    Expert confirmé
    Homme Profil pro
    Analyste/ Programmeur
    Inscrit en
    juillet 2013
    Messages
    2 200
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Bouches du Rhône (Provence Alpes Côte d'Azur)

    Informations professionnelles :
    Activité : Analyste/ Programmeur

    Informations forums :
    Inscription : juillet 2013
    Messages : 2 200
    Points : 4 878
    Points
    4 878

    Par défaut

    Citation Envoyé par martopioche Voir le message
    Gné ??? C'est quoi le "code final" ?
    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).

  19. #39
    Membre confirmé
    Profil pro
    Inscrit en
    décembre 2006
    Messages
    607
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : décembre 2006
    Messages : 607
    Points : 640
    Points
    640

    Par défaut

    Citation Envoyé par foetus Voir le message
    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)
    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 :

    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.

    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.
    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…).

  20. #40
    Membre confirmé
    Profil pro
    Inscrit en
    décembre 2006
    Messages
    607
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : décembre 2006
    Messages : 607
    Points : 640
    Points
    640

    Par défaut

    Citation Envoyé par CodeurPlusPlus Voir le message
    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 :
    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 ?

Discussions similaires

  1. Réponses: 25
    Dernier message: 06/01/2013, 18h22
  2. Faut-il commenter son code source pour le rendre plus lisible et maintenable ?
    Par mayayu dans le forum Débats sur le développement - Le Best Of
    Réponses: 149
    Dernier message: 09/11/2009, 03h30
  3. Bien commenter son code Java
    Par shaun_the_sheep dans le forum Général Java
    Réponses: 2
    Dernier message: 27/05/2008, 12h13
  4. Comment commenter son code source proprement ...
    Par basnifo dans le forum MFC
    Réponses: 3
    Dernier message: 31/03/2006, 17h22

Partager

Partager
  • Envoyer la discussion sur Viadeo
  • Envoyer la discussion sur Twitter
  • Envoyer la discussion sur Google
  • Envoyer la discussion sur Facebook
  • Envoyer la discussion sur Digg
  • Envoyer la discussion sur Delicious
  • Envoyer la discussion sur MySpace
  • Envoyer la discussion sur Yahoo