Auteur Sujet: Faire un code compréhensible  (Lu 8278 fois)

Hors ligne SorenS

  • Membre Junior
  • **
  • Messages: 91
  • Karma: +0/-0
  • Développeur web PHP
    • Kueny Raphaël - Développeur web php
Faire un code compréhensible
« le: 09 juin 2009 à 16:46:37 »
Ces derniers temps je m'amuse à coder des trucs pour les autres par ci par là. Un système de news, de commentaire, de combat. Bref, j'engrange de l'expérience. Du coup, mes codes n'ont pas pour but d'être maintenu par moi. Ceci entraine automatiquement une structure du code, des commentaires etc...

J'ai pris comme habitude de nommer mes variables, mes classes en anglais et de laisser mes commentaires en français. De plus j'utilise un pseudo-système MVC, je mets des commentaires type doc-PHP et je fais une petite doc utilisateur.

Je pense que cela est suffisant, qu'en pensez vous ? Comment faites-vous de votre côté ?
--- Développeur web php passionné de jeux web ---

Hors ligne Prelude

  • Administrateur
  • Membre Héroïque
  • *****
  • Messages: 1155
  • Karma: +9/-0
    • Mon blog
Re : Faire un code compréhensible
« Réponse #1 le: 09 juin 2009 à 17:29:46 »
Ne fournissant pas mes codes pour raisons professionnelles, je n'ai pas, normalement, à commenter mes codes (je suis seul à développer).
Mais... Etant donner que notre métier évolue très vite, il n'est pas rare de se demander à quoi ce que tel ou tel morceau de code peut bien servir.
J'ai donc pris l'habitude de commenter mes fonctions de la façon suivante :
//-----------------------------------
// Que fais la fonction, à quoi elle est destinée ...
// CE : les Conditions d'Entrée (paramètres, exemple ...)
// CS : les Conditions de Sortie (exemple ...)
//
function maFontion(...) {
Ca, c'est pour les fonctions.
Ensuite je conserve un fichier texte à la racine du site contenant tout ce qu'il me semble bon de savoir pour qu'une autre personne puisse reprendre le site sans se prendre la tête.
J'y place en général l'emplacement des fichiers de configuration, les variables globales utilisées, la façon dont est nommé les variables, les fichiers à modifier si changement de serveur ...
Travaillant en POO, je n'ai pas beaucoup de doc à faire puisque tout est fait en grande partie une fois pour toute.
Et, quoiqu'il en soit, lorsque je fais un truc tordu (du genre $a = $a xor $a), je met des annotations pour dire ce qu'il m'est passé par la tête pour écrire ce genre d'ânerie (ici : je veux mettre 0 dans $a).
L'indentation a une importance vitale pour la lecture d'un code propre. Là encore, les avis divergent sur la façon d'indenter. Par exemple, je fais comme ça : (Ce n'est qu'un exemple)
for($i=0;$i<10;$i++) {
     if($i==1) {
           break;
     }
}

Alors que l'on voit souvent cette façon d'indenter :
for ($i=0;$i<10;$i++)
{
     if($i==1)
     {
           break;
     }
}

Quelque soit la méthode, il faut indenter !

Je dois avoir d'autres méthodes... Là comme ça, je ne vois pas... Je reviendrais...

Hors ligne guile

  • Membre Junior
  • **
  • Messages: 56
  • Karma: +1/-0
Re : Faire un code compréhensible
« Réponse #2 le: 10 juin 2009 à 03:07:20 »
Dans mon boulot, dès mon arrivée, on a insisté sur le fait de respecter une norme de codage, ce que j'ai compris et accepté : je sais ce que c'est que de relire du code moche. En plus, il faut dire que si on me surprend à avoir écrit du code pas joli à lire, on me le fait remarquer.
Ma principale difficulté est de passer de ma syntaxe de codage à celle de mon boulot.
J'ai tiré quelques enseignements intéressants sur tout ça.

J'utilise comme SorenS le phpDoc qui permet aux IDE de générer les aides contextuelles sans soucis, et de façon complète et personnalisée. J'écris mes commentaires en français, et pour être original, j'utilise des noms de variables et de fonction en français non concis.
Pourquoi Français? J'aime lire du code presque comme je lirais du français :
if ($Perso->peutAttaquer() && $Adversaire->estAttaquable()) {
    $Perso->Attaquer($Adversaire);
}
D'ailleurs l'utilisation du français est selon moi un avantage comparé aux anglais : il n'y a aucune confusion de lecture immédiate entre le code système (les fonctions du langages) et le code à soi.

Pourquoi non concis? Je hais les variables de type a (désolé Prélude), ou tmp, toto, swap, nType.
Il m'arrive d'utiliser des variables (ex : spr) pour dire qu'elle sera utilisée comme pointeur de sprite, et cela suffit dans ce cas. Mais je me suis interdit la variable tmp. Elle doit avoir une signification plus précise. ex : tmpValeurCalculee. Ne parlons pas de toto!
Mes variables sont donc plutôt longues à écrire (vive l'auto-completion des IDE!), de façon à ce qu'elles n'aient aucune ambigüité en relisant le code. ex :
if (bChoix1erPersoAFaire == TRUE) {
   ...
}
Ceux qui me diront de "oui mais le compilateur peut être limité en nombre de caractère pour la variable", je leur répondrai de voir le petit baton après les deux X du numéro de siècle actuel.

Pour ce qui est de l'indentation, et bien c'est facile : les IDE disposent de formateurs de code. J'écris, il formate. Et je m'énerve quand il le fait mal!

Je tiens également à insister sur le fait d'espacer les opérateurs. C'est une règle à ne pas dénigrer : un opérateur bien espacé est un opérateur visible!
Le code de Prélude ci-dessous
for($i=0;$i<10;$i++) {
     if($i==1) {
           break;
     }
}

Deviendrait alors
for ($i = 0; $i < 10; $i++) {
     if ($i == 1) {
           break;
     }
}

Pour les commentaires, j'ai tendance à en mettre un peu partout, même pour me répéter. Quand c'est sioux, c'est comme Prélude, j'y vais de bon coeur. Quand le mécanisme est complexe, alors là je me lâche! Une de mes fonctions que j'ai soignée (elle est très très très importantes pour l'intégrité des données) fait 162 lignes... dont 93 lignes de codes effectives (et j'ai compté 25 lignes de requêtes SQL).


D'ailleurs! Les requêtes SQL sont souvent oubliées dans l'indentation, la présentation du code!
J'ai la cruelle habitude de placer mes structures de requêtes de façon distinctes, en majuscule, et tout le reste en minuscule (table, champ)
SELECT
   monchamp1,
   monchamp2
FROM
   matable
WHERE
   monchamp3 = 4
   AND monchamp2 < monchamp1

UPDATE
   matable
SET
   monchamp2 = monchamp1 + 2
WHERE
   monchamp3 > monchamp1
Dans ces exemples, ça ne paraît pas ultime, mais quand on se tape des requêtes plus complexe, le SQL redevient un langage comme un autre qu'il faut donc indenter pour y voir plus clair.

Evidemment toutes ces règles que je m'impose évoluent au fil du temps. Elles deviennent plus strictes, plus formelles, plus complètes. Quand je relis un code d'il y a 6 mois, je suis étonné de voir comment j'avais pu oser écrire ainsi.

Hors ligne Prelude

  • Administrateur
  • Membre Héroïque
  • *****
  • Messages: 1155
  • Karma: +9/-0
    • Mon blog
Re : Faire un code compréhensible
« Réponse #3 le: 10 juin 2009 à 07:42:55 »
Citer
Je hais les variables de type a (désolé Prélude)
Faut pas. Ce n'était qu'un exemple. Je n'utilise que dans certains cas ces variables avec une seule lettre :
 - les boucles : $i, $j ...
 - les références à un graph : $x et $y (voir $z)
 - je n'utilise pas tmp, mais dummy pour une variable qui peut être dégagée et n'a pas d'intérêt sorti de son contexte.

Et oui, pour la séparation des opérateur  ;)

Hors ligne keke

  • Animateur
  • Membre Junior
  • *****
  • Messages: 89
  • Karma: +3/-0
    • Magdales
Re : Faire un code compréhensible
« Réponse #4 le: 10 juin 2009 à 09:20:13 »
En PHP, je n'indente jamais mon SQL pour des raisons de place à l'affichage.

J'essaye autant que possible d'envoyer mes requêtes SQL dans des fonctions simples, quitte à ce qu'elles ne fassent que cette requête.

Je suis pas du genre à employer des noms de variable à rallonge, même si ça perd de sa compréhension immédiate :

$total_marche  me semble plus limpide que $iLaSommeDeTousLesValeursEnArgentGeneriqueDuMarcheActuellementCalcule.

Mais je pense qu'il s'agit effectivement plus d'habitude de code que d'une réelle approche dans le cadre d'une reprise du code par un autre développeur.
D'ailleurs certains outils de développement permettent l'auto-complétion du nom de variable, chose que mon petit VI/VIM ne me permet pas ... Ca ne me pousse pas à utiliser des noms à rallonge.

Par ailleurs je suis du genre à formater mon code ainsi.
for ($i=0;$i<10;$i++)
{
     if($i==1)
     {
           break;
     }
}

J'ai beaucoup de mal à suivre l'autre type d'indentation.

Bonne journée à vous !

Kéké qui va peut-être changer de mission ... pour faire du code en PHP ^^
Kéké : administrateur de Magdales.

Hors ligne SorenS

  • Membre Junior
  • **
  • Messages: 91
  • Karma: +0/-0
  • Développeur web PHP
    • Kueny Raphaël - Développeur web php
Re : Faire un code compréhensible
« Réponse #5 le: 10 juin 2009 à 09:44:47 »
Je suis tout à fait d'accord avec ta manière de faire Guile.

En revanche, Kéké je ne comprends pas cette phrase :
"En PHP, je n'indente jamais mon SQL pour des raisons de place à l'affichage."

Perso, je fais ainsi :
SELECT     id, nom, vie
FROM        table_joueur
WHERE     defense >= 10

La lecture est tout de même plus aisée que
SELECT id, nom, vie FROM table_joueur WHERE defense >= 10

(pour des requêtes plus compliquées bien entendu ^^). De plus, j'essaye de ne pas dépasser les 80 caractères par ligne (sur les IDE vous remarquerez une petite barre à cette endroit là. Du coup, écrire les requêtes ainsi me permettent cela.

J'aligne aussi mes affections de variable pour bien les voir d'un seul coup. Je m'explique. (peut-être est-ce que vous entendez par : "séparation des opérateurs")

$this->name      =     htmlentities($name);
$this->life        =     htmlentities($life);
$this->power     =     htmlentities($power);
(l'un des alignements bug à l'affichage, mais vous avez compris le concept je pense)
--- Développeur web php passionné de jeux web ---

Hors ligne keke

  • Animateur
  • Membre Junior
  • *****
  • Messages: 89
  • Karma: +3/-0
    • Magdales
Re : Re : Faire un code compréhensible
« Réponse #6 le: 10 juin 2009 à 10:32:47 »
Sorens > je réagissais au message suivant de Guile :

D'ailleurs! Les requêtes SQL sont souvent oubliées dans l'indentation, la présentation du code!
J'ai la cruelle habitude de placer mes structures de requêtes de façon distinctes, en majuscule, et tout le reste en minuscule (table, champ)
SELECT
   monchamp1,
   monchamp2
FROM
   matable
WHERE
   monchamp3 = 4
   AND monchamp2 < monchamp1

UPDATE
   matable
SET
   monchamp2 = monchamp1 + 2
WHERE
   monchamp3 > monchamp1
Dans ces exemples, ça ne paraît pas ultime, mais quand on se tape des requêtes plus complexe, le SQL redevient un langage comme un autre qu'il faut donc indenter pour y voir plus clair.

Si tu fais ainsi, tu affiches 2 requêtes sur ta page, ce qui empêche d'appréhender le reste du code ... C'est une perte de lisibilité.

La méthode que tu emplois est moins extrème, mais reste selon moi, trop éclatée. Contrairement à du code PHP, le SQL est un langage assez simple du fait de sa structure.
Il m'arrive de sauter une ligne en cas de jointure particulière ou d'une union.

J'espère avoir répondu à ta question ^^. Si ce n'est pas le cas, dis le moi.

Kéké
Kéké : administrateur de Magdales.

Hors ligne SorenS

  • Membre Junior
  • **
  • Messages: 91
  • Karma: +0/-0
  • Développeur web PHP
    • Kueny Raphaël - Développeur web php
Re : Faire un code compréhensible
« Réponse #7 le: 10 juin 2009 à 10:47:46 »
Oui en effet autant pour moi. Je trouve qu'il faut tout de même un peu présenter le code SQL mais je suis d'accord que la méthode de Guile est assez hard :) Je la trouve moins dans ma logique :)

En revanche, je n'aime pas trop laisser ma requête en brut, je me perds rapidement. Il m'arrive de reprendre certains codes de ce genre :
select * from matable where x=1

C'est une véritable horreur ^^ niveau confort de lecture berk !!!

--- Développeur web php passionné de jeux web ---

Hors ligne Prelude

  • Administrateur
  • Membre Héroïque
  • *****
  • Messages: 1155
  • Karma: +9/-0
    • Mon blog
Re : Faire un code compréhensible
« Réponse #8 le: 10 juin 2009 à 11:34:11 »
Ha oui tiens. Mes requêtes SQL sont indentées aussi, mais pas autant que Guile  ;)
Je nomme également mes variables avec une convention toute bête : un petit "g" devant une variable signifie quelle est globale. Par exemple $gLeTitreDeMonSite est une variable globale.
En fait, lorsque l'on travaille en équipe, il est très important de mettre en place des conventions. Un développeur peut toujours être malade et tout le monde ne fait pas dans l'extreme programming.

Hors ligne guile

  • Membre Junior
  • **
  • Messages: 56
  • Karma: +1/-0
Re : Faire un code compréhensible
« Réponse #9 le: 10 juin 2009 à 21:55:50 »
Pour moi il y a deux domaines à séparer : la nomenclature de codage et la nomenclature de nommage. Même si leur bonne pratique est indispensable, les deux n'ont pas pour moi le même but.
La nomenclature de codage permet une bonne lecture du code, la nomenclature de nommage permet une bonne compréhension du code.

De plus, en réfléchissant à vos remarques sur mes pratiques (hard core), je voulais réagir, mais cela n'aurait pas été constructif (le genre d'explications avec lesquelles nous pourrions partir en argumentation incessante). J'en suis alors arrivé à cette conclusion (que je laisse libre d'évoluer) :
- une nomenclature est au départ arbitraire. Certains points sont basés sur une réflexion, ont une justification quelconque qui se tient. Mais à la base, le but est de définir un socle commun, une cohérence d'ensemble.
- chacun ses petites habitudes, ses préférences (qu'on ne peut d'ailleurs discuter) et il est intéressant de voir que l'on se définit une nomenclature en fonction de ses besoins.

Je vais un peu développer ce dernier point.
J'ai commencé très tôt à bosser sur des bases de données (mon premier stage réellement technique me faisait travailler sur une appli tournant sur Oracle 8 et ayant des requêtes SQL de malade, un schéma de plusieurs centaines de tables). Je me suis ensuite spécialisé dans ce type de compétence. De plus je me suis rendu compte que certains traitement étaient bien mieux réalisé avec le SQL qu'avec un traitement PHP. Ainsi, mon code s'articule souvent autour de requêtes.

Quand de votre point de vue vous verriez une requête prenant inutilement de la place, j'y vois une nouvelle partie de mon programme.
Il est vrai que, parfois, ça prenne un peu trop de place mais je m'y accommode : j'en fais abstraction quand je n'ai pas besoin de la lire. De plus, avec la coloration syntaxique il est très facile de ne pas s'attarder sur certaines couleurs...

Pour le préfixage des variables, au lieu de s'attarder en tautologies, autant lire ces articles :
http://fr.wikipedia.org/wiki/Notation_hongroise
http://fr.wikipedia.org/wiki/CamelCase à comparer au "underscore lowercase".

Hors ligne khiguard

  • Modérateur
  • Membre Complet
  • *****
  • Messages: 119
  • Karma: +4/-0
    • Alonya: jeu de gestion et de stratégie.
Re : Faire un code compréhensible
« Réponse #10 le: 11 juin 2009 à 10:24:03 »
Je fait plus ou moins tout ce que vous faites en général.

Je fait juste un truc en plus, c'est noter la provenance des crochet de fermeture (de boucle ou de condition) pour m'y retrouver plus facilement d'un seul coup d'œil quand je ferme successivement 4,5 boucle/condition et que je doit insérer quelques chose entre la 3ème :)

EX:
for 1.... {
     for 2 ... {
            if 1 .... {
                     ....
            }//fin de if 1
            ....
     }//Fin de for 2
}// fin de for 1
@+
Sombre Destin : Jeu de gestion/stratégie.
Alonya : Jeu de gestion/stratégie par partie. (en construction)
Acdn : Webzine ludique.

Hors ligne keke

  • Animateur
  • Membre Junior
  • *****
  • Messages: 89
  • Karma: +3/-0
    • Magdales
Re : Re : Faire un code compréhensible
« Réponse #11 le: 11 juin 2009 à 11:14:42 »
Je fait juste un truc en plus, c'est noter la provenance des crochet de fermeture (de boucle ou de condition) pour m'y retrouver plus facilement d'un seul coup d'œil quand je ferme successivement 4,5 boucle/condition et que je doit insérer quelques chose entre la 3ème :)

EX:
for 1.... {
     for 2 ... {
            if 1 .... {
                     ....
            }//fin de if 1
            ....
     }//Fin de for 2
}// fin de for 1

Il m'arrive de le faire aussi, mais uniquement lorsque l'intérieur des boucles est très long. De même pour les else

If (1)
{
...
}]
else // du if (1)
{
...
}

Mine de rien, ça aide beaucoup ^^
Kéké : administrateur de Magdales.

Hors ligne KiwiToast

  • Membre Complet
  • ***
  • Messages: 158
  • Karma: +1/-0
Re : Faire un code compréhensible
« Réponse #12 le: 12 juin 2009 à 15:09:12 »
Et la gestion des fichiers .php, vous faites comment ?

Vous les mettez dans plein de dossiers différents ? Vous faites beaucoup de fichiers ou seulement quelques uns ?

Au début, je faisais pas beaucoup de gros fichiers, que je mettais dans plein de dossiers ... Maintenant, je fais plus de petits fichiers, mais je les laisse tous dans le même dossier. ^^

Hors ligne Prelude

  • Administrateur
  • Membre Héroïque
  • *****
  • Messages: 1155
  • Karma: +9/-0
    • Mon blog
Re : Faire un code compréhensible
« Réponse #13 le: 12 juin 2009 à 15:27:37 »
Je préfère séparer en plusieurs dossiers (que ce soit Php ou autre) :
 - les includes
 - les class
 - les fichiers générés
 - les css
 - les js
 - les images

Je n'aime pas avoir à la racine pleins de fichiers. Par contre, pas de souci pour que ce soit dans un dossier. mais il ne faut pas trop en mettre sous peine de ralentir un peu le serveur (enfin bon, en dessous de 200 / 300, pas de souci).

Hors ligne guile

  • Membre Junior
  • **
  • Messages: 56
  • Karma: +1/-0
Re : Faire un code compréhensible
« Réponse #14 le: 22 juin 2009 à 22:57:22 »
Dans la lignée de ce sujet, un ticket parlant de l'optimisation d'un code pour la lecture :
http://www.brendel.com/consulting/blog/2009/06/read-optimized-source-code.html