Qu'est-ce qu'un code "propre" selon vous ?

**Matthieu Brucher** · 16/05/2009, 20h56

Envoyé par pseudocode

Non, justement. Le commentaire a pour but d'expliquer ce que l'auto-documentation du code n'explique pas.

L'auto-documentation doit s'arrêter a ce qui est utile pour l'utilisateur du code ( celui qui va appeler la fonction ). Ici l'auto-documentation (= le nommage) explique que la fonction calcule une racine carré. C'est tout ce que l'appelant a besoin de savoir.

Pour avoir plus d'informations, il y a le commentaire : on utilise l'algo de Newton-Raphson. Cette information n'est pas primordiale pour utiliser la fonction, mais elle l'est pour comprendre comment elle fonctionne.

Je ne suis pas d'accord. OK, c'est l'algorithme de Newton-Raphson, mais quand on écrit l'algorithme à la main, pour le comprendre, on donne des noms explicites pour comprendre le fonctionnement de l'algorithme. Pourquoi ne pas le faire dans le code ? On est obligé d'aller sur wikipedia (ou dvp) pour voir exactement la même chose, mais avec des noms explicites ?

**benwit** · 16/05/2009, 21h02

Personnellement, je distinguerai les commentaires publiques des commentaires privés.

Les commentaires privés sont ceux qui se situent à l'intérieur du code, dans le code d'une méthode par exemple. Ils sont destinés au développeur, à celui qui maintient le code. Il ne faut pas qu'ils soient superflus. Si les variables/méthodes sont bien nommés, c'est souvent suffisant. Ils doivent seulement apparaître pour expliquer un choix, aider à la compréhension, ...
Je me suis rendu compte que j'en utilise peu souvent.

Les commentaires publiques sont ceux qui sont "extérieur" au code. C'est par exemple la description de ce que fait une méthode, les entrées attendus et les sorties fournies, les exceptions levées, etc ... Cela peut paraître parfois superflu quand on a accès au source d'un code suffisamment explicite mais ils ne sont pas destinés au développeur de la classe. Ils sont destinés au client de la classe, celui qui l'utilise, qui lui n'a pas accès au source. Cela concerne donc le code réutilisable (APIs par exemple).

En Java, la distinction est facile : Les commentaires apparaissant dans la Javadoc sont ceux que je qualifie de publiques. Tous les autres sont ceux que je qualifie de privés.

Sinon, je trouve aussi que la notation hongroise devrait être évité. D'autant qu'avec des outils modernes comme eclipse, on peut immédiatement connaître le type.

**pseudocode** · 16/05/2009, 21h05

Envoyé par Matthieu Brucher

Pourquoi ne pas le faire dans le code ? On est obligé d'aller sur wikipedia (ou dvp) pour voir exactement la même chose, mais avec des noms explicites ?

Parce que le code n'est pas la pour remplacer un tutorial, ou une démonstration de mathématique. D'autant plus que l'implémentation choisie ne reflète pas toujours la théorie, ou que le langage ne permet pas d'exprimer les concepts (par exemple les nombres complexes, les réels/flottants, ...)

Je ne vais pas pouvoir expliquer a un débutant la théorie du quicksort-recursif-inplace juste en choisissant judicieusement mes noms de variables. Il est plus simple de mettre un commentaire "// on utilise le quicksort-recursif-inplace" au dessus de la fonction "void sort(int[] data)"

Extrait du JRE (java/util/Arrays.java):

Code java :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
8
9
10
11
12
13
14
 
/**
 * Sorts the specified array of ints into ascending numerical order.
 * The sorting algorithm is a tuned quicksort, adapted from Jon
 * L. Bentley and M. Douglas McIlroy's "Engineering a Sort Function",
 * Software-Practice and Experience, Vol. 23(11) P. 1249-1265 (November
 * 1993).  This algorithm offers n*log(n) performance on many data sets
 * that cause other quicksorts to degrade to quadratic performance.
 *
 * @param a the array to be sorted
 */
public static void sort(int[] a) {
  ...
}

**mayayu** · 16/05/2009, 21h07

Envoyé par Matthieu Brucher

Je ne suis pas d'accord. OK, c'est l'algorithme de Newton-Raphson, mais quand on écrit l'algorithme à la main, pour le comprendre, on donne des noms explicites pour comprendre le fonctionnement de l'algorithme. Pourquoi ne pas le faire dans le code ? On est obligé d'aller sur wikipedia (ou dvp) pour voir exactement la même chose, mais avec des noms explicites ?

Avoir des noms explicites de variables dans les algorithmes complexes apporte un peu plus de compréhension, mais ne se substitura pas à une documentation tierce plus complète (comme wikipedia) qui l'explicite clairement.

Même si tu nommes "r" en "approximation_root", dans wikipedia il est fort possible que ça s'appelle "F(x)" et dans une autre "R(n)" (par exemple).

**hegros** · 16/05/2009, 21h13

Envoyé par benwit

Les commentaires publiques sont ceux qui sont "extérieur" au code. C'est par exemple la description de ce que fait une méthode, les entrées attendus et les sorties fournies, les exceptions levées, etc ...

c'est vrai pour les corps des méthodes et classe qu'il pourrait y avoir une vraie plus-value.

J'ai lu Luc écrire une méthode avec un corps de commentaire comme precondition, postcondition on pourrait ajouter les objets collaborant etc.. je trouve cela déja plus pertinent et généralisable que d'expliquer un algo parce que wikipédia power.

Si on va sur du commentaire dans le code il ne faut pas oublier que cela va être publier donc expliquer un algo...

**Matthieu Brucher** · 16/05/2009, 21h19

Envoyé par pseudocode

Parce que le code n'est pas la pour remplacer un tutorial, ou une démonstration de mathématique. D'autant plus que l'implémentation choisie ne reflète pas toujours la théorie, ou que le langage ne permet pas d'exprimer les concepts (par exemple les nombres complexes, les réels/flottants, ...)

Je ne vais pas pouvoir expliquer a un débutant la théorie du quicksort-recursif-inplace juste en choisissant judicieusement mes noms de variables. Il est plus simple de mettre un commentaire "// on utilise le quicksort-recursif-inplace" au dessus de la fonction "void sort(int[] data)"

Un algorithme se traduit directement dans un langage. Si tu parles d'implémentation choisie, c'est que tu utilises... un autre algorithme.

Je suis désolé, mais un programme n'est que la traduction directe en un langage d'un algorithme. Et si ce sont des détails tels que réels, flottants, complexes, ... ça n'empêche pas de nommer de manière explicite les variables.

Dans ma thèse, j'ai des noms explicites dans mes algorithmes, et ce sont aussi des noms explicites dans le code associé.

Envoyé par emiaille

Avoir des noms explicites de variables dans les algorithmes complexes apporte un peu plus de compréhension, mais ne se substitura pas à une documentation tierce plus complète (comme wikipedia) qui l'explicite clairement.

Même si tu nommes "r" en "approximation_root", dans wikipedia il est fort possible que ça s'appelle "F(x)" et dans une autre "R(n)" (par exemple).

Et il faut alors se poser aussi la question du codage propre des algorithmes.

Je ne dis pas qu'il faut reprendre toute la théorie, il est toujours bien utile de renvoyer à une explication plus complète d'un algorithme, mais si on a des noms explicites, il sera bien plus facile de faire le parallèle entre l'algorithme et le programme.

**benwit** · 16/05/2009, 21h43

Je suis de l'avis qu'une variable explicite sera toujours mieux qu'une variable implicite.

En écrivant ceci, je me disais que c'est même plus général que l'informatique. Personnellement, j'imagine que si on écrivait des math avec des noms plus explicite, cela paraitrait moins abscons ?
On ne le fait surement pas pour aller plus vite (le stylo est lent par rapport à la pensée).
En informatique, c'est probablement pour les mêmes raisons. On peut s'imaginer qu'un nom de variable court est plus rapide à écrire (à défaut de le lire) mais encore une fois, avec des outils modernes et l'autocomplétion, ça va vite aussi.

Comme tout, il y a un juste milieu à trouver, c'est une question de bon sens non ?.

J'écris avec un nom explicite :
- toutes mes variables d'instance .
- les variables locales à une méthode lorsqu'il y en a beaucoup.

Mais il m'arrive de donner un nom très court à une variable si la méthode est courte, pas de confusion possible. Example dans une classe Person :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
/**
 * Retourne une représentation textuelle de la personne.
 *
 * @return Une chaîne de caractères non <code>null</code>.
 */
String toString()
{
    StringBuffer sb = new StringBuffer();
    sb.append(this.firstName).append(SPACE); 
    sb.append(this.lastName).append(SPACE); 
    sb.append(this.birthDate).append(SPACE); 
    sb.append(this.email).append(SPACE); 
    sb.append(this.address);
    return sb.toString();
}

**hegros** · 16/05/2009, 21h46

Envoyé par benwit

Dans un objet métier Person par exemple :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
8
9
10
void toString()
{
    StringBuffer sb = new StringBuffer();
    sb.append(this.firstName).append(SPACE); 
    sb.append(this.lastName).append(SPACE); 
    sb.append(this.birthDate).append(SPACE); 
    sb.append(this.email).append(SPACE); 
    sb.append(this.address);
    return sb;
}

C'est volontaire cette écriture de code avec un void en retour et un return string ? C'est pour donner quelque à manger aux refactorers ou pour que les spécificateurs crient alerte ? Parce que sinon sur un court exemple tu montres que tes pratiques n'empêche pas les erreurs de programmation...

**benwit** · 16/05/2009, 21h53

Envoyé par hegros

C'est volontaire cette écriture de code avec un void en retour et un return string ? C'est pour donner quelque à manger aux refactorers ou pour que les spécificateurs crient alerte ? Parce que sinon sur un court exemple tu montres que tes pratiques n'empêche pas les erreurs de programmation...

Sauf que là, ce n'est pas du copier/coller de code mais une saisie directe dans l'éditeur du forum (Eclipse aurait souligner en rouge mon erreur) et oui, j'ai envoyé trop tôt mon message

. Le temps que je corrige, tu étais derrière la porte avec un baton

Et si j'aurai aimé pouvoir corrigé ma bévue incognito, j'aime bien ce que j'ai souligné en gras dans ta réponse. C'est sûrement une entrée courtoise, peut être ironique ? mais sinon, j'aime bien cette mentalité qui consiste à laisser le bénéfice du doute.
Il m'est arrivé de voir du code, de penser que c'était à priori une erreur puis de m'apercevoir ensuite qu'il y a avait des raisons fondées et que ce n'était finalement pas une erreur. Bon ça n'arrive pas tout le temps non plus ...

Le plus drôle, c'est que je m'en suis rendu compte en voulant rajouter un de ces commentaires publiques dont je faisais état précédemment.

**hegros** · 16/05/2009, 22h00

Envoyé par benwit

et oui, j'ai envoyé trop tôt mon message

. Le temps que je corrige, tu étais derrière la porte avec le baton

C'est plus intéressant d'être là à ce moment

Mais bon c'est un peu dur après tout tu devrais avoir le droit à au mois 2-3 refacto avant que ca aille en prod

**benwit** · 16/05/2009, 22h05

Envoyé par hegros

C'est plus intéressant d'être là à ce moment

Mais bon c'est un peu dur après tout tu devrais avoir le droit à au mois 2-3 refacto avant que ca aille en prod

Oui, c'est vrai ... Et puisqu'on parle de code propre, on pourrait demander au bout de combien de lavage ???

Il y a des tâches qui sont dures à enlever !!!

Plus sérieusement, je crois que le refactoring nous aide à écrire un meilleur code.

**pseudocode** · 16/05/2009, 22h39

Envoyé par Matthieu Brucher

Un algorithme se traduit directement dans un langage. Si tu parles d'implémentation choisie, c'est que tu utilises... un autre algorithme.

Bah... l'algo du quicksort c'est l'algo du quicksort. Pourtant l'implémentation en C et en Haskell n'est pas vraiment la même.

Je suis désolé, mais un programme n'est que la traduction directe en un langage d'un algorithme. Et si ce sont des détails tels que réels, flottants, complexes, ... ça n'empêche pas de nommer de manière explicite les variables.

Dans ma thèse, j'ai des noms explicites dans mes algorithmes, et ce sont aussi des noms explicites dans le code associé.

Effectivement, rien n'empêche de mettre des noms de variables explicites, mais ce n'est pas ca qui aide a la "compréhension" de la théorie derrière l'algorithme. Par contre, ca permet plus facilement de comparer le code avec le document théorique. Encore faut-il que ce document théorique soit indiqué dans le commentaire.

dans mon exemple, je peux renommer "r" en "root" ou en "result"... ce n'est pas ca qui explique l'algo de Newton-Raphson.

Et puis bon, les variables "i" et "j" doivent sans doute être les plus utilisées dans les boucles for(), et on ne peut pas dire qu'elles soient très explicites.

**souviron34** · 17/05/2009, 15h21

Envoyé par hegros

Le code est la documentation. Quand tu as écris 500000lignes de code en langageX tu ne penses pas que c'est suffisamment comme commentaire ?

Certainement pas...

Envoyé par hegros

Morale de l'histoire :

plutôt que de prendre l'habitude de commentez systèmatiquement utilisez plutôt une feuille de brouillon pour vos commentaires persos et laissez le fichier code source que le minimum pour que le programme fonctionne.

Certainement pas..

Envoyé par hegros

Pour ma part les commentaires se limiteraient à une entête du fichier, une cartouche pas de plus.

Certainement pas...

Envoyé par hegros

Cependant pourquoi le faire dans le code source ? Si c'est un choix d'architecture l'architecte devrait en avoir connaissance sans à avoir à ouvrir le fichier source de même que le testeur ou le...

Le code source est un document de programmation. Les choix et raisons technniques est un document de conception logiciel (sur un wiki?). Là ce que tu nous proposes c'est une solution documentaire 2 en 1 ?

Simplement parce que, dans notre métier, il arrrive 90% du temps que l'on ait à travailler sur un code sans avoir la documentation.... qui a disparue... (changement de boîte par exemple), qui n'est plus à jour (n'importe quelle méthode de développement), qui est manquante...

Visiblement, tu n'as pas encore eu affaire à ce genre de choses.. Mais je peux t'assurer que cela fait au moins 90% de notre métier.....

Envoyé par benwit

Les commentaires publiques sont ceux qui sont "extérieur" au code. C'est par exemple la description de ce que fait une méthode, les entrées attendus et les sorties fournies, les exceptions levées, etc ... Cela peut paraître parfois superflu quand on a accès au source d'un code suffisamment explicite mais ils ne sont pas destinés au développeur de la classe. Ils sont destinés au client de la classe, celui qui l'utilise, qui lui n'a pas accès au source. Cela concerne donc le code réutilisable (APIs par exemple).

Non, pour la même raison que ci-dessus....

**benwit** · 17/05/2009, 17h21

Envoyé par souviron34

Non, pour la même raison que ci-dessus....

Je ne comprend pas ton "non" par rapport à mon extrait mais tu vas pouvoir surement m'expliquer ?

Peut être as tu mal interprété mon "Les commentaires publiques sont ceux qui sont "extérieur" au code."
J'ai mis extérieur entre guillemets car ils sont bien dans le fichier source. Ils sont extérieurs aux méthodes, entre les méthodes si tu préfères.

Parce que pour information, ces commentaires que je nomme publiques, il y en a pleins les APIs Java et heureusement pour la javadoc générée !

**souviron34** · 17/05/2009, 17h41

Envoyé par benwit

Je ne comprend pas ton "non" par rapport à mon extrait mais tu vas pouvoir surement m'expliquer ?

Peut être as tu mal interprété mon "Les commentaires publiques sont ceux qui sont "extérieur" au code."
J'ai mis extérieur entre guillemets car ils sont bien dans le fichier source. Ils sont extérieurs aux méthodes, entre les méthodes si tu préfères.

Parce que pour information, ces commentaires que je nomme publiques, il y en a pleins les APIs Java et heureusement pour la javadoc générée !

lol ok dans ce cas-là d'accord..

mille excuses

**benwit** · 17/05/2009, 17h58

Envoyé par souviron34

lol ok dans ce cas-là d'accord..
mille excuses

Y a pas de mal.
J'avais commencé à sortir la 22 long rifle

mais en relisant avant d'appuyer sur la gachette "enter"

, je me suis rendu compte que mon "extérieur" même s'il était entre guillemets pouvait être interprété différemment.

D'ailleurs, c'est tout les avantages de ces commentaires Java, car si la javadoc s'envole, on peut toujours la régénérée et si on ne peux pas, c'est qu'on a perdu les sources

**mayayu** · 17/05/2009, 18h01

Envoyé par benwit

D'ailleurs, c'est tout les avantages de ces commentaires Java, car si la javadoc s'envole, on peut toujours la régénérée et si on ne peux pas, c'est qu'on a perdu les sources

C'est aussi tout l'avantage de Doxygen pour le C++.

**hegros** · 17/05/2009, 18h05

Envoyé par souviron34

Simplement parce que, dans notre métier, il arrrive 90% du temps que l'on ait à travailler sur un code sans avoir la documentation.... qui a disparue... (changement de boîte par exemple), qui n'est plus à jour (n'importe quelle méthode de développement), qui est manquante...

Visiblement, tu n'as pas encore eu affaire à ce genre de choses.. Mais je peux t'assurer que cela fait au moins 90% de notre métier.....

Disons que je distingue simplement les différents documents qui puissent exister dans un projet tu ne peux pas tout mettre dans le code de même que la génération automatique de documentation (c'est un des seuls interet à écrire un commentaire de code) n'est pas la seule solution d'organisation documentaire !

Le commentaire de l'algo de sort en java me sert complétement à rien mais franchement c'est chiant tout ces octets gaspillés.

Dans 90% des projets les programmeurs qui documentent ne savent pas le faire aussi bien que pseudocode par exemple moi même y compris.

Pour te répondre souviron, oui j'ai affaire à ce genre de chose tout le temps et à chaque fois les commentaires de code ne me serve à rien sur un projet ou l'autre (je ne parle pas de démonstration ou tutoriaux par exemple mais de production)

Plutot que de devoir faire du code source un fourre tout documentaire je serais plus partisan d'utiliser un outil de rétro-ingénierie de code et d'annotez à guise puis de documenter

**DranDane** · 18/05/2009, 11h17

Pour moi il y a une seule règle primordial : éviter la redondance. En partant de cette règle découle toute une autre série de règles secondaires tel que

- Travail par méthode et fonction afin de faire appels à celles-ci au lieu d'acrire plusieurs fois des mêmes portions de code.
- Nommer intelligemment ses méthodes et variables tout en essayant de ne pas être redondant dans la nomination de celles-ci.
- Pas de hardcoding
- ...

J'aime assez bien l'exemple suivant que je rencontre très souvent

Soit 3 méthodes

GetUserDataByName(string name)
GetUserDateByID(int ID)
GetUserDataByIDCardNumber(int IDCardNumber)

Les ByName, ByID et ByIDCardNumber sont inutiles car on a déjà cette information dans la siganture de la méthodes. On peut donc les supprimer :

GetUserData(string name)
GetUserDate(int ID)
GetUserData(int IDCardNumber)

Le problème c'est que du coup on a deux méthodes avec une même signature. Cela nous permet de nous rendre compte que l'on utilise peut être mal les types de variables. Mieux vaut peut être travailler avec les types Guid et un CardNumber maison.

Donc

GetUserData(string name)
GetUserDate(Guid id)
GetUserData(CardNumber cardNumber)

Voilà, comme ca c'est propre.

**Hephaistos007** · 18/05/2009, 11h36

Envoyé par DranDane

Soit 3 méthodes

GetUserDataByName(string name)
GetUserDateByID(int ID)
GetUserDataByIDCardNumber(int IDCardNumber)

Les ByName, ByID et ByIDCardNumber sont inutiles car on a déjà cette information dans la siganture de la méthodes. On peut donc les supprimer :

GetUserData(string name)
GetUserDate(int ID)
GetUserData(int IDCardNumber)

Ton exemple va même au delà du simple problème de nommage, car dans le second cas tu fais intervenir de la surcharge de méthode. Surcharger une méthode engendre un coût de résolution (lookup) de la méthode à appeler, qui n'existe pas dans la première solution. Du coup, le second code est-il réellement plus "propre" ?

Qu'est-ce qu'un code "propre" selon vous ?

Débats sur le développement - Le Best Of

Discussions similaires

Partager

Partager