Mes conseils pour avoir un code propre

[vtuning.net]

Salut,

Je me permets de créer un énième topic sur la "présentation" du code.

Je voudrais juste donner mon avis et mes méthotes pour avoir un code PHP propre.

Ce n'est certainement pas LA méthode mais elle me convient.

Si ca peut aider certains débutants, j'en serais heureux.

Je dois avouer que la présentation de beaucoup de projets "libres" est pour moi illisible du fait surtout que les fonctions est autres if, else ont leur
ouverture sur la même ligne, ce que je ne trouve pas pratique.

Ca fait maintenant plusieurs années que j'utilise PHP pour mes scripts. Je suis passé par plusieurs type de présentation. Voici ce que j'ai retenu :

les commentaires

J'ai commencé la programmation en PHP sans commenter mon code. Ce fut une énorme erreur. Il est tellement plus simple de se repérer avec des commentaire
structurés et cohérents.
Mais il ne faut surtout pas en abuser, un code trop commenté devien lui aussi illisible.

J'utilise plusieurs types de commentaire pour structurer le code. Les voici :

1er niveau

Code :

1
2
3
4
 
//================================
// Commentaire de premier niveau
//================================

Je l'utilise pour structurer le code en paragraphes

2eme niveau

Code :

1
2
3
4
 
//---------------------------------
// Commentaire de deuxième niveau
//---------------------------------

Je l'utilise pour structurer le code en sous paragraphes.

3eme niveau

Code :

1
2
 
//Commentaire simple

Je l'utilise pour commenter les petites parties du code, comme une variable ou une boucle simple.

Vous remarquerez que pour les commentaires de 1er et de second niveau les = et - se terminent deux caractères après le texte de commentaire.

Les commentaires PHPDocumentor

Surtout ne les oubliez pas, ils vous faciliteront la programmation sous des IDE telles que Eclipse ou Zend Developpement.
La plus part des IDE, proposent l'autocomplétion. Ces commentaires seront très utiles pour que l'IDE sache quoi afficher.

Voici les principaux que j'utilise :

Dans une classe :

Quant vous déclarez une variable vous pouvez mettre une ligne au dessus de celle ci, ce genre de commentaires qui va indiquer à l'IDE que le contenu de
la variable sera une chaîne de caractères.

Code :

1
2
3
4
5
6
7
8
9
10
 
class ma_classe
{
    /**
     * Description de la variable
     *
     * @var string
     */
    var $ma_variable = "";
}

Vous auriez pu aussi utiliser array, int, bool, etc... afin de spécifier le type de votre variable

Vous pouvez aussi le raccourcir en :

Code :

1
2
3
4
5
6
7
8
 
class ma_classe
{
    /**
     * @var string
     */
    var $ma_variable = "";
}

Si vous allez instancier une autre classe dans la variable de la classe principale, vous pouvez déclarer le nom de la classe secondaire afin de
faciliter le travail de l'IDE.

En détails voici ce que ca donne :

Code :

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
 
class ma_classe
{
    /**
     * @var ma_classe_secondaire
     */
    var $ma_variable = "";
} 
 
class ma_classe_secondaire
{
    /**
     * @var string
     */
    var $ma_variable = "";
}
 
$class_ma_classe = new ma_classe;
 
$class_ma_classe->ma_variable = new ma_classe_secondaire;
 
// Ainsi si vous appelez
 
$class_ma_classe->ma_variable->...
 
// L'autocomplétion sera disponnible sur la classe secondaire.

Tout ceci est à peu près identique pour les fonctions

Voici ce que ca donne pour une fonction contenant plusieurs paramètres :

Code :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
 
class ma_classe
{
    /**
     * Description de la fonction
     *
     * @param array $a Tableau d'entrée
     * @param int $b Un nombre
     * @param bool $c true ou false
     * @param string $d une chaîne de caractères
     */
    function ma_fonction( $a, $b, $c, $d )
    {
 
    }
}

Votre function est ainsi plus facilement comprise par le moteur d'autocomplétion de l'IDE. Il peut ainsi vous afficher les différents types acceptés.

J'ai pris pour exemple une classe, mais ceci est aussi applicable hors contexte de classe.

L'indentation.

A mon avis, l'indentation est plus importante que les commentaires. Un code non indenté est quasiment illisible.
Dans cette section je parlerai de ce que j'appelle d'indentation horizontale et verticale.

AEREZ VOTRE CODE !!!

Commençons par l'indentation verticale.

Les "{" sont affichées au même niveau et en dessous de la fonction/boucle à qui ils appartiennent.
Le code qu'ils délimitent est écrit en dessous des "{" et est indenté de 4 espaces.
La fermeture se fait au même niveau que l'ouverture, une ligne en dessous du code.

Le code suivant la fermeture est espacé d'un retour à la ligne.

Ce qui donne :

Code :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
$ma_variable = 0;
 
function ma_fonction( $a )
{
    $a++;
 
    return $a;
}
 
$result_fonction = ma_fonction( $ma_variable );
 
if ( $result_fonction == 0 )
{
    echo "0";
}
else
{
    echo "1";
}
 
unset( $ma_variable );
 
exit();

L'indentation horizontale.

Ce qui est entouré par des ( ) est indenté d'un espace.

Exemple

Code :

1
2
3
4
5
 
function ma_fonction( $a )
{
 
}

La «,» placée après le code n'a pas d'espace avant.
Un espace apès la «,» est appliqué.

Exemple

Code :

1
2
3
4
5
 
function ma_fonction( $a, $b, $c, $d )
{
 
}

Le caractère de concaténation que j'utilise est le «.». J'applique un espace avant et après.

Exemple

Code :

1
2
 
echo 'Texte ' . 'd\'exemple';

Les tableaux.

Comme du code est plus simple qu'une longue description, voici le code.

Code :

1
2
3
4
5
 
$mon_tableau = array( 'conteneur_1' => 'Texte du conteneur 1', 'conteneur_2' => 'Un autre texte', 
                      'conteneur_3' => 'Encore du texte',      'conteneur_4' => 1 );
 
echo $mon_tableau['conteneur_1'];

L'appel de fonctions.

Voici un exemple de création et d'appel de fonction complexe.
Pour améliorer l'exemple, j'y couple une condiation.

Code :

1
2
3
4
5
6
7
8
9
10
11
12
 
function ma_fonction( $a, $b, $c, $d )
{
    return $a;
}
 
$i = 1;
 
$ma_variable = ma_fonction( ( $i == 1 ) ? true : false, 
                            "abcd", 
                            1, 
                            2 );

Voici maintenant un code d'example pour mettre tout cela en application.

Code :

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
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
 
<?
/**
 * Classe qui ne sert absolument à rien
 */
class example
{
    /**
     * Contiendra la classe calculs
     *
     * @var calculs
     */
    var $ma_classe_de_calcul = '';
 
    /**
     * Additionne deux nombres
     *
     * @param int
     */
    function additionne( $a, $b )
    {
        return $a + $b;
    }
 
    /**
     * Soustrait deux nombres
     *
     * @return int
     */
    function soustrait()
    {
        return $this->nombre_1 - $this->nombre_2;
    }
 
    /**
     * Affiche le contenu d'un tableau
     *
     * @param array $array Tableau
     */
    function affiche_tableau ( $array = array() )
    {
        echo '<pre>';
 
        print_r( $array );
 
        echo '</pre>';
    }
}
 
/**
 * Un peu de maths
 */
class calculs
{
    /**
     * Premier nombre à prendre en compre pour le calcul
     *
     * @var int
     */
    var $nombre_1 = '';
 
    /**
     * Deuxième nombre à prendre en compre pour le calcul
     *
     * @var int
     */
    var $nombre_2 = '';
 
    /**
     * Additionne deux nombres
     *
     * @return int
     */
    function additionne()
    {
        return $this->nombre_1 + $this->nombre_2;
    }
 
    /**
     * Soustrait deux nombres
     *
     * @return int
     */
    function soustrait()
    {
        return $this->nombre_1 - $this->nombre_2;
    }
}
 
//===============================================
// Début du script et instanciation des classes
//===============================================
 
$classe_principale = new example;
 
$classe_principale->ma_classe_de_calcul = new calculs;
 
 
//----------------
// Calcul simple
//----------------
 
echo $classe_principale->additionne( 10, 10 );  // Affiche 20
 
echo '<br />';
 
echo $classe_principale->soustrait( 10, 10 );  // Affiche 0
 
echo '<br />';
 
 
//---------------------------------------
// Calculs en utilisant le modèle objet
//---------------------------------------
 
// Attribution des valeurs aux variables
 
$classe_principale->ma_classe_de_calcul->nombre_1 = 10;
$classe_principale->ma_classe_de_calcul->nombre_2 = 10;
 
// Lancement des calculs
echo $classe_principale->ma_classe_de_calcul->additionne(); // Affiche 20
 
echo '<br />';
 
echo $classe_principale->ma_classe_de_calcul->soustrait(); // Affiche 20
 
echo '<br />';
 
 
//------------------------------------
// Affichage du contenu d'un tableau
//------------------------------------
 
$mon_tableau = array( 'conteneur_1' => 'Texte du conteneur 1', 'conteneur_2' => 'Un autre texte', 
                      'conteneur_3' => 'Encore du texte',      'conteneur_4' => 1 );
 
$classe_principale->affiche_tableau( $mon_tableau );
 
 
//=============================================================
// Laisons de côté la classe et amusons nous avec les boucles
//=============================================================
 
unset( $classe_principale, $mon_tableau );
 
echo 'C\'est parti pour les boucles<br />';
 
// Si $i vaut 1 $status passera à true
$status = false;
 
for ( $i = 1 ; $i <= 10 ; $i++ )
{
    echo $i . "<br />";
 
    if ( $i == 1 )
    {
        $status = true;
    }
}
 
echo '<br />';
 
// Vérification du status de la variable $status
if ( $status == true )
{
    echo '$i vallait 1<br />';
}
else
{
    echo '$i ne vallait pas 1<br />';
}
 
 
//===================================
// Passons maintenant aus fonctions
//===================================
 
$i = 10;
 
function test( $a, $b, $c, $d )
{
    //On a besoin juste de $a
 
    echo $a;
}
 
echo test( ( $i == 10 ) ? '<br />$i vaut 10' : '<br />$i ne vaut pas 10', 
           intval( 20 ), 
           30, 
           40 );
 
unset( $i );
?>

Merci de m'avoir lu, et bon codage.

A+

[Lo-chan]

Super topic, merci !

J'espère que les débutants passeront par ici ! Car des fois, je tombe sur des scripts où je suis obligée de réaligner le code car sinon c'est carrément illisible !!!

[Je m'adresse à ceux qui n'utilisent pas ces différentes règles de base] Si vous arrivez à vous lire, tant mieux pour vous ! Pensez aux personnes qui veulent vous lire. Ca décourage énormément et c'est une énorme perte de temps de lire de tels codes. Surtout sur un forum d'entraide, ça sent l'ignoration de post ! Les claviers sont tous équipés des touches "entrée" et "tabulation", elles n'ont pas été inventées pour rien.

Question à l'auteur, tu voudrais bien nous rajouter un petit paragraphe sur les entêtes de fichier. Tu sais les déclarations de licenses, de variables, des autres fichiers inclus, l'auteur du fichier, la date de création... et j'en passe. Ca serait aussi très intéressant. J'ai jamais su les présenter avec une normalisation clair et précise.

[Yogui]

Pour information, Adrien Pellegrini a déjà publié quelque chose à ce sujet --> http://a-pellegrini.developpez.com/t.../coding-style/

[mikaweb]

Voici un topic que je vais m'empresser de recommander à certains amis qui codent comme des ...porcs
Tu as du prendre du temps et je t'en remercie, c'est très bien expliqué et pour une fois cela semble cohérent.
Sinon le lien de Yogui est lui aussi très bien fait.

[vtuning.net]

Merci pour vos commentaires

En ce qui concerne le headers de fichiers PHP, je ne les utilises pas du tout...

Mais à mon avis tu peux utiliser une présentation du genre :

Code :

1
2
3
4
5
6
7
8
 
/**
 *Fichier PHP
 *...
 *...
 *...
 *...
 */

[Lo-chan]

Oui je sais et c'est tout ce que je connais avec quelques lignes qui débutent par des @ (@author, @copyright, @package,...).

Je cherche à savoir exactement comment on complète les lignes et au niveau des licenses ? Je connais l'affichage de la license GPL mais il y en a d'autre. Les entreprises qui vendent des logiciels développés en PHP vont par mettre une license GPL sur leurs fichiers.

[afrodje]

Interressant pour les débutants