Commenter son code :
Pourquoi, quand et comment, un excellent tutoriel par benbout

Le , par Benbout, Membre régulier

J’aime développez.net. Je survole le site de temps à autre, aussi bien pour étoffer ma culture informatique que pour prendre plaisir à dialoguer avec d’autres “rois de la boucle”. On partage nos savoirs, notre impuissance face à un problème et tout cela nous amène à un moment ou à un autre à devoir partager du code.
Et force est de constater que presque à tous les coups, le code n’est pas commenté. Est ce propre aux programmeurs qui côtoient ce site ? Bien sur que non, et pour cela, un rapide survol de quelques projets hébergés sur GitHub ou GitLab, pour ne citer qu’eux, souligne à quel point le développeur informatique (en se gardant bien d’en tirer des conclusions hâtives) a tendance à sous-estimer les bienfaits du commentaire. Alors, pourquoi tant de dédains pour un // # /**/ ?

La raison qui se cacherait derrière cet apparent désamour serait bien souvent la même que celui face aux tests unitaires. “C’est chiant”. Oui, peut être, mais d’autres situations sont à prendre en compte. Parfois, c’est la culture de l’entreprise qui tend à laisser de côté le commentaire. On doit assumer la surcharge de travail, respecter les délais, alors on priorise, et on en oublie le bon sens. Nous pourrions passer des heures à théoriser sur la faible utilisation du commentaire. Tout le monde irait de sa petite anecdote croustillante basée sur son expérience en entreprise ou sur ses projets personnels collaboratifs, mais la n’est pas le sujet de ce court article. Mon but est avant tout de rappeler aux développeurs, occasionnels comme professionnels, ce qu’est un commentaire et ce qu’il n’est pas, lui démontrer l’importance de son utilisation, et peut être raviver la flamme entre eux.

Commenter != documenter

Séparons une fois pour toute l’expression documenter de commenter.

Documenter, c’est fournir la description de son application, de tous ses points d’accès publics et de ses dépendances.
Exemples:

  • Tel objet est utilisé pour faire ceci ou cela, telle méthode est utilisée avec N paramètres et retournera ou non tel type de valeur.

  • La bibliothèque X dépend des bibliothèques Y et Z. Il est nécessaire d’utiliser au minimum la version 4.10 de la bibliothèque Y.

  • L’application ne prend pas en charge, dans la version 0.7RC-2, les échanges avec le service X.



La documentation est générée et utilisée aussi bien par le(s) développeur(s) de l’application qu’un éventuel client de l’application. La plupart du temps, on consulte la documentation soit à partir d’outils propre à l’IDE utilisé, soit directement sur un terminal ou sur une application tierce (un browser par exemple).

Commenter, c’est décrire l’implémentation d’un objet, d’une méthode, d’une propriété, ou de toute variable spéciale (en somme, d’une classe et de ses membres), quand la nécessité ou le besoin de confort l’exigent.
Exemples de commentaires:

  • La méthode Toto fonctionne de telle sorte, elle appelle la méthode Nono et modifie la propriété X qui sera multiplié par 3 si la valeur de X n’excède pas 10.

  • Cette collection peut être vide, et si c’est le cas, la variable Y est réinitialisée.

  • Si cette méthode est utilisée dans tel contexte, alors l’objet assigné à la variable X sera déréférencé et l'événement Z sera levé.

  • Cette méthode implémente le contrat de postcondition X car elle doit respecter la norme Y citée dans la documentation de l’application (cf: link). Contacter X_Z avant toute modification du contrat.

  • Un opérateur implicite est utilisé ici pour telle raison.


Quand doit on commenter

La question qui revient souvent est “quand doit on commenter ?”. J’y ai déjà répondu en partie lors de la description du commentaire. Quand la nécessité ou le besoin de confort l’exigent, tout simplement. Je vous vois venir avec vos haussements d’épaules … et je les comprends. Il est vrai qu’il n’est pas toujours aisé de savoir si le comportement de telle portion de notre code doit être commenté ou non. D’autant que lorsqu’on a pas l’habitude de commenter, on est moins à l’aise pour le faire. Tout comme le vélo, cela s’apprend, et l'intérêt du commentaire, c’est qu’il ne faut pas assimiler le dernier framework à la mode pour apprendre à en faire.

Puisque les exemples sont toujours plus parlant, rien de mieux qu’un code source pour prendre quelques notes ... si je puis m’exprimer ainsi. J’ai décidé d’ouvrir le capot du framework .NET de Microsoft car je l’utilise assez souvent. Si vous ne connaissez ni le framework, ni le langage C#, peu importe, cela n’aura aucune incidence pour la compréhension de cet article. Prenons la classe de la List, l’une des plus célèbres collections d’objets utilisées en .NET.
>> Voir le code source sur le site de Microsoft

La nécessité

Code c# : Sélectionner tout
1
2
3
4
5
6
7
8
9
10
11
// Implements a variable-size List that uses an array of objects to store the 
// elements. A List has a capacity, which is the allocated length 
// of the internal array. As elements are added to a List, the capacity 
// of the List is automatically increased as required by reallocating the 
// internal array. 
//  
[DebuggerTypeProxy(typeof(Mscorlib_CollectionDebugView<>))] 
[DebuggerDisplay("Count = {Count}")] 
[Serializable] 
public class List<T> : IList<T>, System.Collections.IList, IReadOnlyList<T> 
{


Pour ceux qui seraient en froid avec la langue de Shakespeare:

“Implémente une liste de taille variable qui utilise un tableau d’objets pour stocker ses éléments. Une liste a une capacité, qui est la taille du tableau interne. Quand un élément est ajouté à la liste, la capacité de la liste est automatiquement augmentée si nécessaire par réallocation du tableau interne.”

Ce commentaire est un commentaire résultant d’un besoin de confort, mais dans ce cas précis, devient une nécessité. En effet, toute classe doit être commentée pour en décrire brièvement le fonctionnement interne. Dans le cas de cette liste, elle utilise un tableau pour son stockage interne et la méthode employée pour assurer sa “dynamicité” se base le plus simplement du monde sur une réallocation. L’information est utile, voire nécessaire pour appréhender la lecture de la classe. Voyez la différence avec la documentation de notre List :

Code c# : Sélectionner tout
1
2
3
4
5
6
7
8
9
// Résumé : 
// Représente une liste fortement typée d'objets accessibles par index. // Fournit 
// des méthodes de recherche, de tri et de manipulation de listes. Pour 
// parcourir le code source .NET Framework pour ce type, consultez la 
// Référence Source. 
// 
// Paramètres de type : 
//   T: 
//     Type d'éléments de la liste.


La documentation s’occupe uniquement de décrire l’objet tel qu’il est utilisable par l’utilisateur.

Pour les besoins de cet article, je switch brièvement sur l’un des constructeurs de la classe ArrayList avant de revenir à notre List :

Code c# : Sélectionner tout
1
2
3
4
5
// Note: this constructor is a bogus constructor that does nothing 
// and is for use only with SyncArrayList. 
internal ArrayList( bool trash ) 
{ 
}

Si vous n'êtes pas un habitué du framework .NET, le mot clé internal est un modificateur d’accès. En l'occurrence, cela signifie que notre constructeur ne peut être utilisé que dans cette assembly.
Remarquez le commentaire, sa présence est une nécessité. En effet, SyncArrayList est une classe dérivée de ArrayList. Sans ce commentaire, vous penseriez qu’il s’agit d’un constructeur sans utilité pour notre ArrayList, ce qui est le cas, mais vous ne sauriez pas qu’il est utilisé pour une classe fille qui elle en aura besoin. Vous seriez à même de penser qu’il serait peut être envisageable de le supprimer. Vous décideriez, peut être, par pragmatisme, de vérifier s’il n’y a aucunes références dans le code d’autres classes, car après tout, cela semble étrange à première vue et vous finiriez par tomber sur une référence dans la classe SyncArrayList. Cette réflexion, puis sa recherche associée, serait une perte de temps inutile qui peut être prévenue par un simple commentaire de deux lignes...
Revenons en à notre List.

Le besoin de confort

Code c# : Sélectionner tout
1
2
3
4
5
6
7
8
9
// Adds the given object to the end of this list. The size of the list // is 
// increased by one. If required, the capacity of the list is doubled 
// before adding the new element. 
// 
public void Add(T item) { 
    if (_size == _items.Length) EnsureCapacity(_size + 1); 
    _items[_size++] = item; 
    _version++; 
}

Remarquez qu’ici, l’implémentation de la méthode est brève. Ce code ne nécessite pas à proprement parler d’un commentaire pour en décrire son fonctionnement. Le commentaire* répond ici à un besoin de confort. D’abord, ce commentaire nous rappelle ce que nous savions déjà par la lecture du commentaire de la classe, mais, comme la méthode fait principalement appel à une autre méthode privé dans la classe ( .EnsureCapacity() ), un bref résumé du comportement des deux méthodes est énoncé. Cela nous évite d’aller nous renseigner dans le commentaire de la méthode appelée.

*si le commentaire semble bizarrement mis en page, il s’agit du formatage de google docs, n’y prêtez pas attention.


Parlons taille

Vous vous en doutez, il est déconseillé d’écrire de longs commentaires. Plus les commentaires sont longs, plus ils risquent de distraire le programmeur et de réduire la lisibilité d’un fichier. Il est donc plus ou moins convenu qu’un commentaire ne devrait pas excéder 5 lignes. Cependant, il y a des cas ou il est utile de générer un commentaire long. Ces cas pourraient être les suivants :

  • La méthode / propriété utilise un algorithme complexe qu’il est nécessaire de détailler pour rendre rapidement abordable sa compréhension.
  • La méthode utilise une méthode d’une autre classe, il est alors plus confortable pour le programmeur de comprendre le fonctionnement de l’autre méthode et de son incidence dans la première sans avoir à aller jusqu’à la source de cette méthode et de revenir sur sa feuille de travail pour en tirer un bilan.
  • La méthode a beaucoup de surcharges (au moins 3) et certaines appellent l’une d’entre elles, voire plusieurs. Il est alors plus lisible d’écrire un long commentaire au dessus de la première méthode que de diviser les commentaires pour chaque méthodes surchargées.


Les commentaires spéciaux

De nos jours, la plupart des IDE proposent quelques snippets pour insérer des commentaires spéciaux. Les plus connus sont les TODO et les FIXME. En quoi sont ils spéciaux ?
Les TODO, comme les FIXME, sont des commentaires qui présentent le code non pas tel qu’il est mais tel qu’il devrait, ou devra être. La nuance est subtile mais notable. Ainsi, mélanger des commentaires décrivant l’objet informatique tel qu’il est implémenté, et d’autres, tel qu'il le devrait ou le sera, peut créer des confusions.

Cependant, il faut reconnaître que ces types de commentaires ont le mérite d’exister car peuvent se révéler très utile dans certaines situations. Le programmeur veillera à les utiliser avec parcimonie, et, essaiera de les isoler du reste des commentaires. Une bonne pratique serait peut être de les “encapsuler” au top du fichier, et non de les déposer directement à l’endroit ou ils doivent renseigner.

Gravé dans le code

Le principal défaut du commentaire, c’est qu’il affirme la vérité, un fait qui ne peut être remis en cause. Le commentaire est une transcription du langage informatique vers le langage naturel, et un code informatique est par essence toujours vrai, sa lecture ne peut pas être soumise à interprétation, seulement à compréhension. De ce fait, cette transcription n'est qu'unidirectionnelle, le langage humain étant lui interprétable.

Le problème étant que, quand le commentaire est faux, il est toujours considéré comme vrai par ses lecteurs, et de la, peut induire un certain nombre d'erreurs en cascade.

Restons toujours sur notre List, car il y a justement un exemple parfait pour illustrer ce que je suis en train de vous énoncer :

Code csharp : Sélectionner tout
1
2
3
4
5
6
7
// 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; 
}

Dans cet exemple, le commentaire nous informe qu’une liste instanciée avec ce constructeur aura une capacité de 0, et que, lors de l’ajout du premier élément, la capacité sera augmenté à 16, et qu’en suite, elle sera multipliée par deux à chaque fois que le tableau interne sera plein. Pour notre plus grand bonheur, ce commentaire est faux et le code lui dit toujours la vérité :

Code csharp : Sélectionner tout
private const int _defaultCapacity = 4;

La capacité de la liste sera en effet de 0, mais lors de l'insertion du premier élément, la capacité sera fixée à 4 et non à 16 :

Code : Sélectionner tout
1
2
3
4
5
6
7
8
9
10
11
private void EnsureCapacity(int min)  
{ 
	if (_items.Length < min) { 
		int newCapacity = _items.Length == 0? _defaultCapacity : _items.Length * 2; 
		// Allow the list to grow to maximum possible capacity (~2G elements) before encountering overflow. 
		// Note that this check works even when _items.Length overflowed thanks to the (uint) cast 
		if ((uint)newCapacity > Array.MaxArrayLength) newCapacity = Array.MaxArrayLength; 
		if (newCapacity < min) newCapacity = min; 
		Capacity = newCapacity; 
	} 
}

Nous supposerons, avec une certaine assurance, que le programmeur a du écrire le commentaire avant d’oublier de modifier la propriété _defaultCapacity.
Le danger, comme j’ai tenté de le souligner plus haut, est que le commentaire lui sera toujours considéré comme vrai. Il ne peut être remis en question. On peut aussi noter que le code ne semble pas être couvert par les tests, ou que ceux-ci sont eux aussi dépréciés et confirment au programmeur que tout fonctionne pour le mieux dans le meilleur des mondes alors que ce n’est pas le cas. Dans ce cas précis, cela n'entraîne pas d’erreurs en cascade, mais vous savez très bien ce que cela peut induire dans un cadre différent.

Conclusion

Les commentaires sont nécessaires au développement d’une application, et on ne peut pas parler de maintenabilité du code sans y inclure l’importance du commentaire. Que vous utilisiez des tests unitaires et/ou des contrats conditionnels pour vos membres de classe, rien ne peut être plus important que les commentaires dans la prévention de comportements non souhaités dans votre application. Ces derniers renseignent, avertissent, annotent. Ils évitent au programmeur d’aller chercher l’information utile ailleurs, limitent la distraction de l’Homme derrière la machine, focalisent ce dernier sur la feuille de travail et l’accompagne dans l’écriture, l’édition et la factorisation du code. Les commentaires vulgarisent les comportements et les algorithmes. Aucun programmeur ne devrait s’en priver ou en priver ses confrères. Il faut tout de même les utiliser avec parcimonie et veiller à ce qu'ils soient fidèles au code commenté, sinon, cet outils peut devenir plus dangereux qu'utile à son propriétaire.

N’est il pas temps de vous réconcilier avec le commentaire ? Jusqu'où devra-t-il aller pour vous séduire ?


Vous avez aimé cette actualité ? Alors partagez-la avec vos amis en cliquant sur les boutons ci-dessous :


 Poster un commentaire

Avatar de CinePhil CinePhil - Modérateur https://www.developpez.com
le 19/03/2018 à 12:29
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
	/** 
	 * 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.
Avatar de Benbout Benbout - Membre régulier https://www.developpez.com
le 19/03/2018 à 21:29
Citation Envoyé par CinePhil;bt7559
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
	/** 
	 * 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.
Avatar de la_urre la_urre - Nouveau membre du Club https://www.developpez.com
le 20/03/2018 à 16:39
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 : Sélectionner tout
1
2
3
4
5
6
7
public 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
Avatar de Benbout Benbout - Membre régulier https://www.developpez.com
le 20/03/2018 à 17:19
Citation Envoyé par la_urre Voir le message
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 : Sélectionner tout
1
2
3
4
5
6
7
public 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
Salut la_urre !

Code : Sélectionner tout
* 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 : Sélectionner tout
1
2
3
4
5
6
// 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.
Avatar de fpignalet fpignalet - Nouveau Candidat au Club https://www.developpez.com
le 21/03/2018 à 8:02
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)
Avatar de Aurelien.Regat-Barrel Aurelien.Regat-Barrel - Expert éminent https://www.developpez.com
le 21/03/2018 à 17:25
Citation Envoyé par fpignalet Voir le message
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.
Avatar de MaPommeTao MaPommeTao - Membre régulier https://www.developpez.com
le 25/03/2018 à 18:44
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.
Avatar de RedGuff RedGuff - Membre régulier https://www.developpez.com
le 11/04/2018 à 0:04
J'ai repris mes études (environ 6 mois sur 1 an) : pas un seul commentaire par les profs.
Contacter le responsable de la rubrique Accueil