Discussion :

[pseudocode]

Question : est-ce que quelqu'un à un exemple de code source qu'il considère comme étant du "code propre" ?

[mayayu]

Un code propre rime pour moi avec code maintenable.

Voilà quelques règles que je m'applique pour obtenir un "code propre" selon mes critères :

• un fichier CPP et un fichier H par classe (aussi petite soit-elle),
• utiliser la notation hongroise pour les noms de fonctions et de variables,
• utiliser les commentaires format "doxygen" pour documenter chaque classe, fonction, variable,
• essayer de faire des fonctions lisibles intégralement sur un écran (30/40 lignes max) mais c'est pas toujours possible,
• aérer le code en sautant des lignes entre chaque groupe d'instructions ayant un sens à être regroupées ensembles,
• commenter systématiquement ces groupes d'instructions,
• une indentation systématique de taille 4 (8 c'est trop) pour chaque boucle ou instructions de test.

Moral de l'histoire : Commentez, commentez, commentez...

[Matthieu Brucher]

• utiliser la notation hongroise pour les noms de fonctions et de variables,

Moral de l'histoire : Commentez, commentez, commentez...

Mouais...
Plus aucune personnalité reconnue du monde de la programmation ne dit de programmer avec la notation hongroise, au contraire, il faut l'éviter comme la peste.
Pourquoi devoir renommer une variable si on a changé son type (passage d'une liste à un vecteur parce que plus adapté) ?

Et les commentaires, c'est la même chose, trop de commentaires tuent le commentaire. Le commentaire doit être présent de manière parcimonieuse pour qu'il ait un impact. Autrement, la fonction doit pouvoir se suffire à elle-même.

[mayayu]

Mouais...
Plus aucune personnalité reconnue du monde de la programmation ne dit de programmer avec la notation hongroise, au contraire, il faut l'éviter comme la peste.
Pourquoi devoir renommer une variable si on a changé son type (passage d'une liste à un vecteur parce que plus adapté) ?

Et les commentaires, c'est la même chose, trop de commentaires tuent le commentaire. Le commentaire doit être présent de manière parcimonieuse pour qu'il ait un impact. Autrement, la fonction doit pouvoir se suffire à elle-même.

Au contraire, je trouve la notation hongroise très utile, ça évite d'avoir à consulter systématiquement la documentation pour connaître le type des variables.
Par ailleurs, si on change sans arrêt les liste en vecteurs, c'est qu'il y a un problème de conception.

Pour les commentaires, je suis d'accord qu'il ne faut pas commenter tout ce que l'on a fait, mais fournir quelques explications peut s'avérer très utile quand ça fait 3/4 ans qu'on a pas mis le nez dans l'application, ou quand c'est une autre personne qui doit le mettre.

[Furikawari]

Mouais...
Plus aucune personnalité reconnue du monde de la programmation ne dit de programmer avec la notation hongroise, au contraire, il faut l'éviter comme la peste.
Pourquoi devoir renommer une variable si on a changé son type (passage d'une liste à un vecteur parce que plus adapté) ?

Et les commentaires, c'est la même chose, trop de commentaires tuent le commentaire. Le commentaire doit être présent de manière parcimonieuse pour qu'il ait un impact. Autrement, la fonction doit pouvoir se suffire à elle-même.

(je prends ce fil en route et comme je uis bien élevé je commence du début, du coup je réponds à une des premières pages )

Faux, faux et archi faux !!!

Le problème de la notation hongroise est que celle que la majorité des gens connaissent (celles promues dans les ouvrages de programmation système windows) n'est pas la notation hongroise telle qu'lle avait été conçue initialement.
Effectivement, utiliser cette notation pour spécifier le type de la variable est quelque peu aberrant. Mais la notation hongroise originale n'avait rien à voir avec le typage, elle portait sur la fonction même de la variable. J'avais lu une anecdote disant qu'elle avait été créé initialement par les développeurs d'excel à cause des changements de coordonnées, la notation permettait de spécifier quel type de coordonnées contenait la variable, et non le type de la variable elle même.
Y'a eu plusieurs bloggers relatant cette histoire, j'avoue que j'ai la flemme de chercher et je laisse les plus motivés d'entre vous retrouver les liens.

Edit: En fait Souviron avait très bien répondu à ce problème avec les liens auquel je pensais

[hegros]

Moral de l'histoire : Commentez, commentez, commentez...

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

Si tu as besoin de t'exprimer sur une fonction, un paramètre beh tu regardes dans le glossaire ou dans une documentation technique mais normalement un code 'propre' ne devrait pas nous amener à aller rechercher une information au fin fond de l'univers il est auto-documentant.


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

[mayayu]

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

Si tu as besoin de t'exprimer sur une fonction, un paramètre beh tu regardes dans le glossaire ou dans une documentation technique mais normalement un code 'propre' ne devrait pas nous amener à aller rechercher une information au fin fond de l'univers il est auto-documentant.


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

Chaque développeur a sa façon de voir les choses; demandes à 2 personnes de te coder la même fonction (un peu complexe), il y aura des différences.
Imagines ce que ça donne sur une application entière.

En ce moment, j'en fais évoluer une (développée en C) que je n'ai pas écrite, elle n'est pas commentée, je ne connais pas le développeur...
Je suis obligé de partir du main et de remonter de fonctions en fonctions (et parfois de fichier en fichiers), jusqu'à trouver ce que je cherche.
Et ça, tout simplement parce que j'aurais pas du tout fait comme il/elle a fait, donc c'est le seul moyen que j'ai.
Petit à petit, on comprend la logique, mais que de temps perdu, quelques indications n'auraient pas été les malvenues...

P.S. 1 :Si tu éprouves le besoin d'avoir des commentaires perso, c'est certainement qu'ils seront aussi nécessaires à ceux qui passeront après toi.

P.S. 2 : Quand je parle de modifier le programme d'un autre, ça m'est déjà arrivé de reprendre mes propres développements quelques années plus tard.
J'ai évolué durant ce temps, et bien si je n'avais pas su que c'était moi qui l'avait écrit, je l'aurais pas deviné.
Les commentaires m'ont été bien utiles.

[pseudocode]

Le code est la documentation.

Ca dépend ce que tu mets dans tes commentaire. Un commentaire ne doit pas expliquer ce que fait le code car cela doit normalement se déduire de la lecture du code (code "auto-documenté"). Un commentaire doit expliquer ce que le code ne dit pas : les raisons qui ont poussé a choisir ce code plutot qu'un autre.

Un petit exemple ?

Code original

Code java :

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

1
2
3
4
r = n / 2;
while ( abs( r - (n/r) ) > t ) {
  r = 0.5 * ( r + (n/r) );
}

Code commenté

Code java :

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

1
2
3
4
5
// square root of n with Newton-Raphson approximation
r = n / 2;
while ( abs( r - (n/r) ) > t ) {
  r = 0.5 * ( r + (n/r) );
}

code auto-documenté (par refactor)

Code java :

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

1
2
3
4
5
6
7
private double SquareRootNewtonRaphsonApproximation(n) {
  r = n / 2;
  while ( abs( r - (n/r) ) > PRECISION ) {
    r = 0.5 * ( r + (n/r) );
  }
  return r;
}

code auto-documenté commenté

Code java :

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

1
2
3
4
5
6
7
8
//  Math.sqrt() replacement using Newton-Raphson algorithm
private double SquareRoot(n) {
  r = n / 2;
  while ( abs( r - (n/r) ) > PRECISION ) {
    r = 0.5 * ( r + (n/r) );
  }
  return r;
}

[programmeur94]

Un code "propre" est un code pour lequel les symboles (identificateurs de variables, fonctions, méthodes, classes), sont correctement choisis. Plus le choix des symboles sera pertinent et plus le code sera lisible et maintenable, bref compréhensible. On peut observer que les auteurs des APIs Java ou .NET ont un souci particulier pour le choix des noms et verbes utilisés. Trop souvent, les développeurs choisissent des noms trop abstraits ou génériques, qui ne nuisent pas au fonctionnement du code, mais nuise à sa compréhension.

[Matthieu Brucher]

Un code "propre" est un code pour lequel les symboles (identificateurs de variables, fonctions, méthodes, classes), sont correctement choisis. Plus le choix des symboles sera pertinent et plus le code sera lisible et maintenable, bref compréhensible. On peut observer que les auteurs des APIs Java ou .NET ont un souci particulier pour le choix des noms et verbes utilisés. Trop souvent, les développeurs choisissent des noms trop abstraits ou génériques, qui ne nuisent pas au fonctionnement du code, mais nuise à sa compréhension.

Complètement d'accord.

[hegros]

Petite remarque sur RAII : c'est bien spécifique au c++ certains langages ne le permettent pas garbages collector ou pas.

Bien que RAII me semble aussi applicable à un niveau au dessus du code c'est à dire quand je conçois mes classes déjà les problématiques de lisibilité/portée de variables/paramètres sont exposées.