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

**souviron34** · 19/05/2009, 10h49

Pour le problème de el_slapper, j'aurais fait la même chose en C que white_tentacle...

Code C :

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
17
18
COURRIER-PRELEVEMENT = CHEQUE ;
switch ( paiement )
{
   case B :
        COURRIER-PRELEVEMENT = AGENT ;
        break ;
 
   case C :
        COURRIER-PRELEVEMENT = SIEGE ;
        break ;
 
  case A :
        if ( Tip_Autorise )
          {
             COURRIER-PRELEVELEMENT = TIP
          }
        break ;
}

ou

Code C :

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
17
18
19
20
21
switch ( paiement )
{
   case B :
        COURRIER-PRELEVEMENT = AGENT ;
        break ;
 
   case C :
        COURRIER-PRELEVEMENT = SIEGE ;
        break ;
 
  case A :
        if ( Tip_Autorise )
          {
             COURRIER-PRELEVELEMENT = TIP
             break ;
          }
 
   default :
        COURRIER-PRELEVEMENT = CHEQUE ;
        break ;
}

1 seul test et une seule assignation...

Envoyé par Franck SORIANO

C'est vrai que sur une doc qui a un peu vécu, il arrive un moment où on ne sait plus si la doc est fiable (surtout si le code semble faire autre chose que la doc).

J'ajouterais également, que malheureusement, c'est la même chose avec les commentaires dans le code. Dès que le code a un peu vécu, tu finis aussi par te demander si les commentaires sont encore fiables.

eh oui.... malheureusement c'est la vie...

Envoyé par hegros

Tu te rends compte de ce que tu dis ? documenter un algo dans le code source c'est parfait pour un tutoriel ou un livre (pour apprendre)pour rendre plus dense, un éditeur de code n'est pas ce qu'il y a de mieux pour documenter.

Non seulement je m'en rend compte, mais je le maintiens avec force

Envoyé par hegros

Aussi, j'ai écris des programmes où chaque caractère d'un commentaire compte comme un octet. Le programme n'est pas chargé en mémoire vive puisque c'est embarqué sur du matériel électronique et ma rom ne fait pas 9pétaoctets pour embarquer le commentaire de l'algorithme de wxy. Bref, cela ne me semble pas généralisable comme approche encore spécifique..

tu racontes n'importe quoi...

Pas un seul compilateur n'embarque les commentaires..

Même pas les noms de variables... D'où l'extrême difficulté à décompiler (et surtout à en comprendre la sortie)...

**hegros** · 19/05/2009, 12h09

Jedai et Souviron > C'est vous qui ne connaissez pas c'est tout le domaine industriel vous êtes plus des tertiaires...

En pascal sur du matériel Schneider TéléMécanique, chaque ligne de commentaire compte comme un octet et biensûr que oui que je vois à l'execution les commentaires en clair dans la mémoire

Il suffit de vérifier avec delphi 6 pour se rende compte que c'est tout à fait la philosophie (1 ligne de commentaire = 1 compilation)

**millie** · 19/05/2009, 12h40

Il y a plein de cas où la signature et le nom de la fonction ne sont pas suffisants et où il est nécessaire de spécificer les entrées et le retour pour les cas d'erreurs

Par exemple pour toutes les fonctions avec des bornes, la méthode substring(int inf, int sup) sur une chaîne de caractère qui retourne une sous-chaîne :
- inf commence t'-il a 0 ou à 1 dans la chaine ?
- sup est il inclus ou non inclus ?
- une borne inf supérieur à une borne sup lêve t'il une exception, où est-ce que ça retourne null ou une chaîne vide ?

Si le commentaire n'est pas présent, le nom de la fonction n'est clairement pas suffisant (pourtant le nom est bien choisi car ça fait ce que ça dit).

**hegros** · 19/05/2009, 13h38

Envoyé par millie

- inf commence t'-il a 0 ou à 1 dans la chaine ?
- sup est il inclus ou non inclus ?
- une borne inf supérieur à une borne sup lêve t'il une exception, où est-ce que ça retourne null ou une chaîne vide ?

C'est spécifique au langage en C c'est 0 en W-Langage c'est 1, bref cela n'a rien à faire comme un commentaire de code (cela ressemblerait à un commentaire du langage...)

Quand au reste je ne trouve pas que apporte une plus-value.

Si le commentaire n'est pas présent, le nom de la fonction n'est clairement pas suffisant (pourtant le nom est bien choisi car ça fait ce que ça dit).

Avec le commentaire c'est surement pas plus clair !

**millie** · 19/05/2009, 13h42

Envoyé par hegros

C'est spécifique au langage en C c'est 0 en W-Langage c'est 1

En fait, c'était un exemple Java (mais cela est valable pour n'importe quel langage).

J'ai pris des String, cela pourrait être n'importe quel objet avec une possibilité d'extraire une sous partie avec des bornes.

Avec le commentaire c'est surement pas plus clair !

Pourtant, cela me semble clair :

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
15
16
17
18
19
20
21
22
23
   /**
     * Returns a new string that is a substring of this string. The
     * substring begins at the specified <code>beginIndex</code> and
     * extends to the character at index <code>endIndex - 1</code>.
     * Thus the length of the substring is <code>endIndex-beginIndex</code>.
     * <p>
     * Examples:
     * <blockquote><pre>
     * "hamburger".substring(4, 8) returns "urge"
     * "smiles".substring(1, 5) returns "mile"
     * </pre></blockquote>
     *
     * @param      beginIndex   the beginning index, inclusive.
     * @param      endIndex     the ending index, exclusive.
     * @return     the specified substring.
     * @exception  IndexOutOfBoundsException  if the
     *             <code>beginIndex</code> is negative, or
     *             <code>endIndex</code> is larger than the length of
     *             this <code>String</code> object, or
     *             <code>beginIndex</code> is larger than
     *             <code>endIndex</code>.
     */
    public String substring(int beginIndex, int endIndex) { ... }

Le fait que les bornes soient inclusives/exclusives est spécifiés. Les indices aussi. Les cas d'erreur aussi. Et 2 exemples sont données.

**hegros** · 19/05/2009, 13h46

Attends tu commentes plus que tu codes...

Non franchement ce code est affreux ce n'est pas plus clair du tout

Pour me répeter mais mise à part pour la génération automatique de code ou test tous tes commentaires, en arrivant sur ton projet, ne me serve foutrement à rien du tout.

**pseudocode** · 19/05/2009, 13h57

Envoyé par millie

Il y a plein de cas où la signature et le nom de la fonction ne sont pas suffisants et où il est nécessaire de spécificer les entrées et le retour pour les cas d'erreurs

Par exemple pour toutes les fonctions avec des bornes, la méthode substring(int inf, int sup) sur une chaîne de caractère qui retourne une sous-chaîne :
- inf commence t'-il a 0 ou à 1 dans la chaine ?
- sup est il inclus ou non inclus ?
- une borne inf supérieur à une borne sup lêve t'il une exception, où est-ce que ça retourne null ou une chaîne vide ?

Si le commentaire n'est pas présent, le nom de la fonction n'est clairement pas suffisant (pourtant le nom est bien choisi car ça fait ce que ça dit).

Ces "commentaires" sont une manière de matérialiser la programmation par contrat. Comme le langage ne gère pas réellement le respect du contrat (au niveau compilation/exécution) ces informations sont insérées sous forme de commentaire. A la charge du développeur de respecter le contrat lors de l'appel. D'ailleurs, en Java/C#/Doxygene, ces commentaires spécifiques sont formalisés par l'utilisation de Tags, afin d'être facilement exploitable.

Pour moi c'est différent du "commentaire" libre qui doit expliquer ce que fait le code (ou comment il le fait).

**millie** · 19/05/2009, 14h10

Envoyé par pseudocode

Ces "commentaires" sont une manière de matérialiser la programmation par contrat. Comme le langage ne gère pas réellement le respect du contrat (au niveau compilation/exécution) ces informations sont insérées sous forme de commentaire. A la charge du développeur de respecter le contrat lors de l'appel. D'ailleurs, en Java/C#/Doxygene, ces commentaires spécifiques sont formalisés par l'utilisation de Tags, afin d'être facilement exploitable.

Pour moi c'est différent du "commentaire" libre qui doit expliquer ce que fait le code (ou comment il le fait).

C'est que benwit appelait des commentaires publiques. Cela reste souvent plus simple à lire que des règles et des axiomes.
Je préfère une API où les méthodes sont spécificés comme ça et sans commentaire privées, que non spécifié avec des commentaires privés

(une méthode va plus souvent être utilisée qu'elle n'est maintenue)

Après, je suis peut être seul à avoir cette avis...

Envoyé par hegros

Attends tu commentes plus que tu codes...

Non franchement ce code est affreux ce n'est pas plus clair du tout

En même temps, je n'ai pas mis de code...
J'ai juste écrit les spécifications de la fonction/méthode, dire que c'est inutile revient à dire qu'écrire des spécifications est inutile (ici on les met dans le code et ils peuvent être extrait automatiquement pour générer les documents de spécifications de l'API).

Ce qui dans mon exemple donnera ça : http://java.sun.com/javase/6/docs/ap...ng(int,%20int))

**white_tentacle** · 19/05/2009, 14h23

Ces "commentaires" sont une manière de matérialiser la programmation par contrat. Comme le langage ne gère pas réellement le respect du contrat (au niveau compilation/exécution) ces informations sont insérées sous forme de commentaire. A la charge du développeur de respecter le contrat lors de l'appel. D'ailleurs, en Java/C#/Doxygene, ces commentaires spécifiques sont formalisés par l'utilisation de Tags, afin d'être facilement exploitable.

Oui, sauf qu'en l'occurrence, les préconditions sont exprimées dans la clause throw, ce qui est assez surprenant (au final, ça veut dire qu'on ne fait pas de la programmation par contrats, mais de la programmation défensive). Mais il y a ce qu'il faut savoir. Si le code que je récupère était toujours comme ça, je serais un homme heureux.

Pour moi c'est différent du "commentaire" libre qui doit expliquer ce que fait le code (ou comment il le fait).

C'est vrai que c'est différent, le contrat fait pratiquement partie de la signature de la fonction. Mais à choisir entre les deux, je préfère très largement n'avoir que le contrat. Au moins, je sais comment utiliser la fonction.

**rad_hass** · 19/05/2009, 14h29

Les méthodes Agiles ne conseillent pas de commenter le code, car elles ne sont jamais mise à jour ... Ce qu'elles conseillent par contre, c'est d'écrire des tests unitaires (en TDD on n'écrit pas de code, sans écrire un test unitaire par exemple), on fait régulièrement du refactoring ...
Les tests unitaires étant mis à jour régulièrement, ils peuvent permettre une meilleure compréhension du code.
Et le refactoring permet d'avoir un code plus propre.

Y a plusieurs approche pour le développement, y a ceux qui voit en la documentation abondante une garantie pour avoir du code évolutif et maintenable et ceux qui croit qu'un code maintenable et évolutif est un code fortement testé et remanié ... Plus ça va et plus je me sens dans la seconde branche, celle du monde agile, car trop vue de doc quand elle existe, soit elle est obsolète, soit qui demande un temps énorme pour en sortir la petite info dont on a besoin.

**millie** · 19/05/2009, 14h38

La maintenance des commentaires et des spécifications sont effectivement un problème déjà souligné dans cette discussion.

Ecrire des tests exhaustifs revient vaguement à écrire et vérifier les axiomes des méthodes.
Il faudrait pouvoir coupler les axiomes et des générateurs d'objets pour pouvoir générer des tests automatiquement

(mais cela reste peu adapté au déroulement de scénario)

Le problème est que la lecture des tests et des axiomes peuvent être lourdingue (les tests peuvent donner des exemples intéressants par contre) et peu adapté à la livraison d'API à d'autres boites/services/public

**el_slapper** · 19/05/2009, 14h44

Envoyé par white_tentacle

(.../...)

C'est très lisible, et en plus, le compilateur est capable de me donner un warning ou une erreur si j'ai oublié un cas dans mon switch (très utile lorsqu'on rajoute un type de paiement).

Cela dit, je viens de regarder rapidement ce que sont des "Niveaux 88", et effectivement, ma remarque initiale ne s'applique pas ici (par contre, le mécanisme même des niveaux 88 me semble plutôt contre intuitif).

Effecitvement, les mécanismes sont assez différents. Le niveau 88 est très puissant(puisqu'il permet de faire se chevaucher des valeurs), mais il est assez délicat au premier abord(d'ou ta remarque sur le contre-intuitif), et il n'est pas sécurisé comme ton switch. Le jour ou on invente un nouveau mode de paiement, la compilation n'y verra que du feu - même si on a ajouté une nouvelle valeur.

Maintenant, qu'est-ce qui est le plus propre? J'en sais rien. Personellement j'aime bien le fait de faire un EVALUATE/Select case(VB) sur un booléen, ça permet de faire une liste de conditions variées, dès qu'on a plus d'un critère d'aiguillage, sans rajouter de IF(dans mon cas, sur le paiement TIP). Ce qui n'est pas possible en Java(pour le peu que j'en connais, un "switch case true", eclipse n'aime pas). Ce qui oblige Souviron à rajouter un if dans son switch. Mais est-ce plus propre? Non, c'est juste que je préfère.

Pour ce qui est de la démarche agile, à mon sens, C'est un choix à haut niveau. Moi modeste programmeur, je suis. Ici, chez mon client actuel, c'est diagramme en V, chiffrage sur 1000 jours et tout le toutim. L'idée même de démarche agile, donc, ne s'applique pas. Même si, sur un plan perso, je trouve ça surpuissant. Et je subodore que ça a aussi des failles(mais je manque d'expérience pour en parler).

**rad_hass** · 19/05/2009, 15h07

Envoyé par millie

La maintenance des commentaires et des spécifications sont effectivement un problème déjà souligné dans cette discussion.

Ecrire des tests exhaustifs revient vaguement à écrire et vérifier les axiomes des méthodes.
Il faudrait pouvoir coupler les axiomes et des générateurs d'objets pour pouvoir générer des tests automatiquement

(mais cela reste peu adapté au déroulement de scénario)

Dans une approche MDA ?

Il me semble (mais mes connaissances ne sont que sommaires à ce niveau) que le code générer est testé à partir des uses cases spécifié, qui sont eux fais automatiquement.

PS : Je parlais de test unitaire !

**hegros** · 19/05/2009, 15h15

Envoyé par millie

En même temps, je n'ai pas mis de code...
J'ai juste écrit les spécifications de la fonction/méthode, dire que c'est inutile revient à dire qu'écrire des spécifications est inutile (ici on les met dans le code et ils peuvent être extrait automatiquement pour générer les documents de spécifications de l'API).

Ce qui est inutile c'est de mettre le commentaire dans le code cela ne revient pas à dire qu'écrire les spécifications est inutile (c'est toi qui le dis pas moi) c'est écrire les spécifications ailleurs dans un autre document.

Le commentaire de ton code ne sera jamais plus à jour qu'un document tierce spécialisé dans les spécifications.

En plus tu sais les difficultés de maintenance soit le commentaire dans le code n'est donc pas une solution satisfaisante.

**millie** · 19/05/2009, 15h18

Envoyé par rad_hass

PS : Je parlais de test unitaire !

De même.

Pour un exemple simple, si on prend les 2 axiomes suivants sur des ensembles immutables avec les fonctions suivantes :

Code :

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

1
2
3
4
5
6
//signature
creerEnsembleVide() -> Ensemble
taille(Ensemble) -> entier
ajouterElement(Ensemble, Element) -> Ensemble
retirerElement(Ensemble, Element) -> Ensemble

Code :

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

1
2
3
4
//axiomes
taille(creerEnsembleVide()) == 0
Pour tous ensembles e, pour tout élément a, retirerElement(ajouterElement(e, a), a) == e

Si on dispose de 2 générateurs :
creerEnsembleAleatoire() -> Ensemble
creerElementAleatoire() -> Element

On pourrait générer les tests unitaires suivants automatiquement :

Code :

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

1
2
3
4
5
6
7
8
//test axiome 1
assertEquals(taille(creerEnsembleVide()), 0);

//test axiome 2 (que l'on peut relancer un certain nombre de fois)
Ensemble  e = creerEnsembleAleatoire();
Element a = creerElementAleatoire();
assertEquals(retirerElement(ajouterElement(e, a), a) , e )

L'exemple est simple ici car ce sont des TAD immutables. Et on peut remarquer qu'il n'y a pas de déroulement de scénario, juste une génération de tests à partir des axiomes.

**hegros** · 19/05/2009, 15h21

milie pour les tests c'est largement défendable cependant ce n'est plus pareil. Ce sont ne plus à mon sens des commentaires comme on le comprends dans le langage usuel des développeurs.

Un commentaire c'est pour expliquer un code là c'est tout différent

**mathbzh** · 19/05/2009, 17h42

Mon petit avis qui ne tiens que de mon expérience.

En général, le code, même compliqué, même non commenté, même avec des noms de variables peu inspiré... reste relativement facile à lire (OK, il y a des bouts de codes de psychopathes particulièrement obscurs mais finalement j'en ai rencontré assez peu dans ma carrière).

Par contre parfois, ce qui peut poser problème c'est l'envie (ou parfois l'obligation) de trop bien faire. La multiplication des niveaux d'abstraction, l'utilisation de classe proxy dans tous les coins, le découpage excessif des responsabilités... l'utilisation d'un tas de pattern (parfois à juste titre)
Font que pour comprendre un bout de code de 10 lignes on finit par parcourir de multiples fichiers de code, à ne plus savoir ce qu'on manipule...

L'enfer est pavé de bonne intention, et parfois pour des intentions louables (alors là, si on sépare le concept A du concept B... on pourra passer facilement de sybase à Oracle ou de Sun à AIX... proposer une interface pour smartphone, connecter l'appli à la machine à café... Un tas de perspectives qui ne seront probablement jamais étudiée sérieusement faute de budget ou parce qu'elles sont irréalistes .

Bref, un code propre doit aussi (en plus de tout ce que vous avez pu définir précédemment) savoir conserver une conception et une architecture raisonnable.

Là ou le bas blesse, c'est qu'un code propre doit en même temps savoir augmenter le niveau d'abstraction, la complexité de la conception, la complexité de l'architecture... quand c'est nécessaire.

Aussi simple que possible, aussi compliqué que nécessaire. Le juste milieu n'est pas si facile à trouver.

**souviron34** · 19/05/2009, 17h50

Envoyé par rad_hass

Les méthodes Agiles ne conseillent pas de commenter le code, car elles ne sont jamais mise à jour ... Ce qu'elles conseillent par contre, c'est d'écrire des tests unitaires (en TDD on n'écrit pas de code, sans écrire un test unitaire par exemple), on fait régulièrement du refactoring ...
Les tests unitaires étant mis à jour régulièrement, ils peuvent permettre une meilleure compréhension du code.
Et le refactoring permet d'avoir un code plus propre.

Y a plusieurs approche pour le développement, y a ceux qui voit en la documentation abondante une garantie pour avoir du code évolutif et maintenable et ceux qui croit qu'un code maintenable et évolutif est un code fortement testé et remanié ... Plus ça va et plus je me sens dans la seconde branche, celle du monde agile, car trop vue de doc quand elle existe, soit elle est obsolète, soit qui demande un temps énorme pour en sortir la petite info
dont on a besoin.

personne ici n'a parlé (en tous cas pas dans ce sous-débat) de documentation externe...

J'aimerais bien qu'on me cite un extrait d'une méthode logiciellle (qu'elle qu'elle soit), agile ou non, recommandant de ne pas mettre de commentaires dans son code.....

Cela va de soi, c'est peut-être pour ça qu'ils l'ont oublié...

Envoyé par hegros

Le commentaire de ton code ne sera jamais plus à jour qu'un document tierce spécialisé dans les spécifications.

En plus tu sais les difficultés de maintenance soit le commentaire dans le code n'est donc pas une solution satisfaisante.

Parce que tu penses que la doc externe est plus à jour que la doc interne ????????????

Dans 99.99999% des cas que j'ai vu, c'est le contraire...

Et j'aime beaucoup le "document tierce"... et surtout sa fiabilité par rapport au code....

J'aimerais beaucoup vous voir, toi ou rad_hass, dans 10 ou 15 ans, en train d'essayer de reprendre un de vos codes... (ou celui d'un autre)....

Enfin bref, que cela soit ce que tu penses, soit, mais s'il te plaît ne vient pas précher pour les autres, alors qu'ici on est un forum de professionnels où il y a des débutants et des jeunes qui viennent puiser...

**souviron34** · 19/05/2009, 17h52

Envoyé par mathbzh

..L'enfer est pavé de bonne intention
...Aussi simple que possible, aussi compliqué que nécessaire. Le juste milieu n'est pas si facile à trouver.

Abosulement..

Bravo por ce résumé synthétique

**mayayu** · 19/05/2009, 17h54

Je suis pleinement de l'avis de souviron34, mais ce n'est visiblement pas le cas de tout le monde.

Si un administrateur passe par là, est-ce qu'il est possible de créer un sondage "Faut-il commenter son code?", ça pourrait être intéressant, je pense, non?

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

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

Discussions similaires

Partager

Partager