J'ai repris mes études (environ 6 mois sur 1 an) : pas un seul commentaire par les profs.
Ayant beaucoup développé des morceaux de codes pour des applications très importantes, j'ai toujours commenté au maximum, surtout dès qu'une pirouette de programmation ou d'écriture est utilisée. Il faut aussi dans ce genre de projets qui perdurent dans le temps (de 1 à 20 ans et parfois plus) que les personnes qui reprennent la suite ou la maintenance puissent avoir des informations. C'est aussi très utile pour la maintenance et la modification suite à la découverte de bogues, quand on reprend un bout de code écrit quelques mois auparavant.
Envoyé par fpignalet 1 - ca consiste non pas a expliquer ce que fait le code, qui est cense respecter des standards de dev et donc etre un minimum clair, mais POURQUOI il le fait. Yep! et j'ajouterais : - expliquer ce que le code ne fait pas et pourquoi Il faut distinguer - je pense - les commentaires sur du code "neuf" qui ne devraient pas être trop nombreux (sinon ils trahissent peut être une complexité de design qui est à revoir) des commentaires sur un code legacy qui a vécu pas mal de modifs. Dans ce dernier cas, les commentaires sont très précieux car ils capturent l'expérience acquise au fil du temps avec ce bout de code, les cas tordus auxquels on ne peut pas / pouvait pas penser lors de son écriture initiale, et qui ont été découverts avec le temps. Ca vaut de l'or! Des fois le détail est donné via une URL vers un système de tickets, mais j'ai souvent constaté que ces outils ne duraient pas aussi longtemps que le code et du coup on perd totalement le descriptif du problème si on s'est pas donné un minimum de mal pour le réexpliquer en commentaire.
Oui, 1000 fois oui. En fait il faut surtout expliquer au refractaires que: 1 - ca consiste non pas a expliquer ce que fait le code, qui est cense respecter des standards de dev et donc etre un minimum clair, mais POURQUOI il le fait. 2 - pour la majeur partie d'entre nous, employes dans une entreprise, ce code appartient a l'entreprise qui nous donne de l'argent tous les mois en echange. Il est donc normal qu'il soit un minimum lisible et comprehensible par d'autres si besoin est. (desole pour les accents: deutsche tastatur)
Salut la_urre ! Code : Sélectionner tout - Visualiser dans une fenêtre à part * If required, the capacity of the list is doubled before adding the new element: ici le commentaire est même perturbant je trouve. Le code fait EnsureCapacity(_size + 1); Est-ce que cela signifie que l'on augmente la taille de 1 uniquement ? Le commentaire aurait donc tort ? En fait, .EnsureCapacity, littéralement garantir la capacité de stockage, check si le tableau est plein, et si c'est le cas, plusieurs choix s'offrent à la méthode. Soit doubler la taille, soit l'ajuster à la taille minimale requise, soit lui attribuer une capacité par défaut (defaultcapacity une constante dans la classe). Le size + 1 passé en paramètre correspond à la taille minimale requise. Dans le cas de l'utilisation de la méthode Add, EnsureCapacity opère un doublement du tableau, et non l'un des deux autres choix, donc il est assez interessant de l'écrire explicitement pour comprendre le fonctionnement de la méthode ensurecapacity et son incidence dans add. Concernant ton exemple (doublesize etc), cela n'aurait pas pu être possible, .EnsureCapacity() ne doublera pas toujours la taille du tableau, comme vu précédemment. Donc pour le coup cela n'aurait pas été possible, mais tu ne pouvais pas le savoir il faut avoir inspecter la classe de cet objet List. La ou je te rejoins entièrement, c'est sur le fait qu'une partie du commentaire est redondant. D'ailleurs, je l'ai souligné dans cet article pour montrer qu'il ne s'agit la non pas d'une nécessite, mais d'un besoin de confort. Et le besoin de confort a un sens assez vague et est relatif à chaque être humain. Dans ton cas, c'est le contraire, cela pourrait te créer un inconfort de lecture. Il faut être vigilant avec les commentaires qui ne sont pas nécessaires, tu as absolument raison. D'ailleurs, toujours dans cette classe, un cas assez comique : Code c# : Sélectionner tout - Visualiser dans une fenêtre à part 123456// Constructs a List. The list is initially empty and has a capacity // of zero. Upon adding the first element to the list the capacity is // increased to 16, and then increased in multiples of two as required. public List() { _items = _emptyArray; } Parfois, les commentaires ne se suffisent pas à eux même. Remarquez que le commentaire énonce explicitement que la capacité d'une liste sera fixée à 16 lors de l'ajout du premier élément par un Add. Hors, dans le code, la taille de la liste sera de 4. Il est fort probable que ce commentaire fut écrit avant d'écrire le code, et que le programmeur ai oublié de faire la modification. Donc un commentaire ne remplacera jamais ni un test unitaire ni un contrat, il fait parti de la trinité triade, si on décide de l'accepter dans ce jeu des trois.
* If required, the capacity of the list is doubled before adding the new element: ici le commentaire est même perturbant je trouve. Le code fait EnsureCapacity(_size + 1); Est-ce que cela signifie que l'on augmente la taille de 1 uniquement ? Le commentaire aurait donc tort ?
// Constructs a List. The list is initially empty and has a capacity // of zero. Upon adding the first element to the list the capacity is // increased to 16, and then increased in multiples of two as required. public List() { _items = _emptyArray; }
Personnellement j'ai l'habitude de coder avec un minimum de commentaires. Mis à part sur une API qui est publique, et parfois sur des en-têtes de classe, je ne commente presque jamais. J'essaie au maximum d'écrire du code qui se suffise à lui-même. Je trouve l'exemple du Add intéressant, car je trouve justement que le commentaire est redondant avec le code et donc inutile. Si je prends ce commentaire morceau par morceau: * Adds the given object to the end of this list. Dans ce cas là, j'aurais peut-être appelé la méthode Append, qui est un terme plus approprié dans ce cas * The size of the list is increased by one: on retrouve un size++ dans le code, ce qui est assez explicite, donc pour moi le commentaire revient à de la paraphrase. * If required, the capacity of the list is doubled before adding the new element: ici le commentaire est même perturbant je trouve. Le code fait EnsureCapacity(_size + 1); Est-ce que cela signifie que l'on augmente la taille de 1 uniquement ? Le commentaire aurait donc tort ? Si je devais écrire cette méthode comme je le fais habituellement, voilà ce que je ferais : Code c# : Sélectionner tout - Visualiser dans une fenêtre à part 123456public void Append(T item) { if (SizeHasReachedCapacity()) DoubleCapacity(); _items[_size++] = item; _version++; } Je trouve ce code suffisamment parlant, et je n'ai pas besoin d'un commentaire qui fait autant de lignes que le code (et qui est potentiellement incorrect). Je crois qu'avec le temps je trouve même les commentaires plus inconfortables que confortables. Il y a de la littérature intéressante à ce sujet dans Clean Code ou Code Complete ou sur le oueb en général
public void Append(T item) { if (SizeHasReachedCapacity()) DoubleCapacity(); _items[_size++] = item; _version++; }
Envoyé par CinePhil Pour ma part, je commente mon code mais de façon très brève pour décrire l'enchaînement des opérations afin de retrouver, parfois bien plus tard, la portion de code qui pose un souci ou que je souhaite améliorer. Exemple actuel : Code PHP : Sélectionner tout - Visualiser dans une fenêtre à part 1234567891011121314151617181920212223242526272829303132333435363738394041 /** * Affiche la liste des inscriptions * @param array $arguments : Liste des arguments permettant de filtrer ou trier la liste */ protected function afficherListe($arguments) { /** Données nécessaires aux filtres du tableau */ // Liste des années universitaires pour lesquelles sont déjà enregistrées des candidatures $objInscription = new Inscription(); $liste_annees_univ = $objInscription->listeAnneesUniversitaires(); // Détermination de l'année universitaire actuelle $annee_univ_actuelle = $this->anneeUnivActuelle(); // Liste des diplômes ensfea $objDiplome = new Diplome(); $liste_diplomes_ensfea = $objDiplome->getListeDiplomesEnsfea(); // Liste des états d'inscription $liste_etat_inscriptions = $objInscription->listeEtatCandidaturesInscriptions('INS'); // Liste des étudiants $liste_etudiants = $objInscription->listerInscriptions($arguments); /** Préparation de la vue */ $vue = new Vue('Inscription', 'listeInscriptions'); $vue->setDonnees(array('login'=>$this->getLogin())); $vue->setDonnees($annee_univ_actuelle, 'annee_univ_actuelle'); $vue->setDonnees($liste_annees_univ, 'liste_annees_univ'); $vue->setDonnees($liste_etudiants, 'liste_etudiants'); $vue->setDonnees($liste_diplomes_ensfea, 'liste_diplomes_ensfea'); $vue->setDonnees($liste_etat_inscriptions, 'liste_etats_inscriptions'); $vue->generer(); /** Génération de la page */ $page = new Page('Liste des inscriptions'); $page->addCssFile('Public/css/listeInscriptions.css'); $page->addChild($vue); $page->afficherPage(); } Il y a aussi les commentaires provisoires (qui durent parfois un temps... assez long ) pour les // FIXME ou autres // TODO. Bref, je vois le commentaire comme un outil de débogage et d'amélioration future du code. Salut CinePhil c'est très bien! En fin de compte, c'est une question de feeling. Dans ton cas, tu les utilises vraiment pour l’annotation en elle même, comme pense bete ou pour soulever un point important pour un debugging futur si j'ai bien compris. Cela diffère un peu de ma vision, je le vois comme un outils plus large que cela dans sa palette de services rendus. Au final, l'important est de le considérer avec bienveillance et non comme quelque chose d'inutile et d'emmerdant (parlons cru ... nous sommes entre nous). D'ailleurs, merci d'avoir parlé des TODO et des FIXME je les ai oublié, je vais les inclure à ce petit article. A bientot.
/** * Affiche la liste des inscriptions * @param array $arguments : Liste des arguments permettant de filtrer ou trier la liste */ protected function afficherListe($arguments) { /** Données nécessaires aux filtres du tableau */ // Liste des années universitaires pour lesquelles sont déjà enregistrées des candidatures $objInscription = new Inscription(); $liste_annees_univ = $objInscription->listeAnneesUniversitaires(); // Détermination de l'année universitaire actuelle $annee_univ_actuelle = $this->anneeUnivActuelle(); // Liste des diplômes ensfea $objDiplome = new Diplome(); $liste_diplomes_ensfea = $objDiplome->getListeDiplomesEnsfea(); // Liste des états d'inscription $liste_etat_inscriptions = $objInscription->listeEtatCandidaturesInscriptions('INS'); // Liste des étudiants $liste_etudiants = $objInscription->listerInscriptions($arguments); /** Préparation de la vue */ $vue = new Vue('Inscription', 'listeInscriptions'); $vue->setDonnees(array('login'=>$this->getLogin())); $vue->setDonnees($annee_univ_actuelle, 'annee_univ_actuelle'); $vue->setDonnees($liste_annees_univ, 'liste_annees_univ'); $vue->setDonnees($liste_etudiants, 'liste_etudiants'); $vue->setDonnees($liste_diplomes_ensfea, 'liste_diplomes_ensfea'); $vue->setDonnees($liste_etat_inscriptions, 'liste_etats_inscriptions'); $vue->generer(); /** Génération de la page */ $page = new Page('Liste des inscriptions'); $page->addCssFile('Public/css/listeInscriptions.css'); $page->addChild($vue); $page->afficherPage(); }
Pour ma part, je commente mon code mais de façon très brève pour décrire l'enchaînement des opérations afin de retrouver, parfois bien plus tard, la portion de code qui pose un souci ou que je souhaite améliorer. Exemple actuel : Code PHP : Sélectionner tout - Visualiser dans une fenêtre à part 1234567891011121314151617181920212223242526272829303132333435363738394041 /** * Affiche la liste des inscriptions * @param array $arguments : Liste des arguments permettant de filtrer ou trier la liste */ protected function afficherListe($arguments) { /** Données nécessaires aux filtres du tableau */ // Liste des années universitaires pour lesquelles sont déjà enregistrées des candidatures $objInscription = new Inscription(); $liste_annees_univ = $objInscription->listeAnneesUniversitaires(); // Détermination de l'année universitaire actuelle $annee_univ_actuelle = $this->anneeUnivActuelle(); // Liste des diplômes ensfea $objDiplome = new Diplome(); $liste_diplomes_ensfea = $objDiplome->getListeDiplomesEnsfea(); // Liste des états d'inscription $liste_etat_inscriptions = $objInscription->listeEtatCandidaturesInscriptions('INS'); // Liste des étudiants $liste_etudiants = $objInscription->listerInscriptions($arguments); /** Préparation de la vue */ $vue = new Vue('Inscription', 'listeInscriptions'); $vue->setDonnees(array('login'=>$this->getLogin())); $vue->setDonnees($annee_univ_actuelle, 'annee_univ_actuelle'); $vue->setDonnees($liste_annees_univ, 'liste_annees_univ'); $vue->setDonnees($liste_etudiants, 'liste_etudiants'); $vue->setDonnees($liste_diplomes_ensfea, 'liste_diplomes_ensfea'); $vue->setDonnees($liste_etat_inscriptions, 'liste_etats_inscriptions'); $vue->generer(); /** Génération de la page */ $page = new Page('Liste des inscriptions'); $page->addCssFile('Public/css/listeInscriptions.css'); $page->addChild($vue); $page->afficherPage(); } Il y a aussi les commentaires provisoires (qui durent parfois un temps... assez long ) pour les // FIXME ou autres // TODO. Bref, je vois le commentaire comme un outil de débogage et d'amélioration future du code.
Catégories
Récents visiteurs
Consulter le profil
Marquer ce blog comme lu
