Tout développeur, que ce soit à l’école ou en apprenant sur le tas, écrit du code. J’espère n’avoir perdu personne à ce stade de l’explication 
Inconsciemment on cherchera à utiliser un style d’écriture avec lequel on se sent à l’aise, qu’on pourra et saura relire facilement et dans le meilleur des cas, qui pourra être relu par une autre personne sans avoir à engager d’interprète.
Tout développeur tend donc à utiliser des conventions de programmation (coding standards), que ce soit en HTML, PHP, CSS, JavaScript ou même en Cobol. Et utiliser des conventions, c’est bien !
Quelle convention de nommage adopter ?
Avant de choisir une convention, encore faudrait-il savoir quelles conventions existent :
- pas de convention
- convention hongroise
- convention PEAR
- convention symfony
- convention Zend Framework
- convention WordPress (que j’abhorre)
- etc.
Autant dire qu’il y a de tout et pour tous les goûts.
Ce qu’il faut retenir d’une convention c’est qu’elle explicite des règles de développement :
- sur le nommage des éléments
- sur l’indentation des éléments
- sur les structures de contrôle (if, else, tout ça quoi)
- sur la syntaxe des commentaires
- sur la syntaxe de la documentation (le code auto-documenté c’est bon !)
- sur l’organisation des fichiers, éventuellement
C’est pour ça que partir sur une convention parfaite sur le papier mais inapplicable est une vaste fumisterie. L’idéal étant de pouvoir reprendre du code dans un projet sans avoir eu besoin de lire la documentation pour en comprendre l’organisation.
Mon conseil : essayez, choisissez mais ne prenez pas non plus trop laxiste en terme de notation.
Une chose est sure : quand on a essayé une belle
Mes conventions de nommage en PHP
J’avoue, la notation utilisée dans symfony m’a tellement plu que je la réutilise quasiment partout. Ci-dessus, une illustration montrant du code pour un plugin WordPress (en PHP 4 malheureusement …). Elle en présente un bon aperçu.
Notation
J’utilise UpperCamelCase pour le nommage des classes sauf s’il y a un préfixe qui, lui, reste en minuscule.
Exemples : class AmazonWidgetsShortcodes, class sfUploader.
Pour ce qui est méthodes de classes, j’utilise lowerCamelCase. Comme ça on sait qu’on reste dans un objet et c’est pas plus mal.
Enfin, pour les fonctions orphelines, helpers & cie, c’est tout en minuscule séparé par des underscore (un nom particulier à ça ? lowered_and_underscored ? )
Exemple : add_filter()
Indentation
Dans l’indentation il y a 2 camps : celui des espaces et celui des tabulations.
J’ai suivi celui des espaces pour une simple et bonne raison : 1 tabulation a une taille différente selon les éditeurs, que ça soit votre IDE, votre shell ou n’importe quel logiciel de texte. L’idéal est d’avoir un rendu identique dans tous les éditeurs sans paramétrage.
En revanche, là encore je suis mais j’aime, je suis sur une tabulation à 2 espaces : c’est bête mais je trouve ça plus esthétique et on arrive moins rapidement à la limite de 80 caractères.
Cette « limite » n’est que virtuelle mais ouvrez un terminal, 80 lignes par défaut. C’est plus confortable de rester en-dessous de ce nombre. Ceci dit je fais quelques exceptions, des fois
Structures de contrôle
On pourrait résumer à 1 ligne = 1 action et 2 types d’utilisation.
Tout d’abord les structures dans le code à proprement parler :
- un espace entre l’opérateur et la parenthèse ouvrante
- un retour à la ligne à chaque accolade
- pas d’espaces dans les lignes vides (résidus d’indentation)
- systématiquement les accolades, même en cas de ligne unique après l’opérateur
- opérateur ternaire quand ça reste simple, pas trop long et plus lisible
Côté templating en revanche j’utilise la syntaxe alternative de PHP à raison d’un opérateur par ligne :
<ol class="posts">
<?php foreach($posts as $post): ?>
<li id="post-<?php echo $post->getId() ?>">
<a href="<?php $post->getPermalink() ?>">
<?php echo $post->getTitle() ?>
</a>
</li>
<?php endforeach ?>
</ol>Syntaxe de la documentation
Enfin, pour terminer sur la partie PHP, PHPDoc est surpuissante en plus d’être simple à utiliser. Comble du bonheur, sa syntaxe est réutilisable dans d’autres langages.
PHPDoc est le principe du code autodocumenté :
- vous commentez votre code avec la syntaxe PHPDoc
- vous générez sa documentation avec le programme PHPDoc (en HTML, PDF etc.)
L’idéal est de documenter en même temps qu’on produit le code. Par principe on revient rarement sur son propre code juste pour le loisir de le décrire, par manque de temps ou par flemme.
Mes conventions de nommage en JavaScript
Ne vous inquiétez pas, je ne vais pas tout recommencer pour JavaScript Je suis à peu près la même logique qu’en PHP à part pour les accolades.
En effet si je conserve un comportement similaire pour les structures de contrôles (1 accolade par ligne) :
- je ne fais pas de retour à la ligne sur les accolades/parenthèse ouvrante d’une fonction/objet anonyme
- je ne fais pas de retour à la ligne après une accolade/parenthèse fermante s’il y a une virgule ou parenthèse après
var OncleTom = {
age: 25,
pensee: function(){
return this.age * Math.random()
}
};Mes conventions de nommage en CSS
Inutile de paraphraser ce que j’ai déjà écris dans mon article sur les bonnes pratiques de codage CSS.
Deux lectures en une oui
Conclusion
Bon au final on voit que ce n’est pas si compliqué que ça d’apporter un brin de rigueur.
On pourra même s’amuser à compléter le tout par la disposition des méthodes et fonctions d ans un fichier par ordre alphabétique (j’en connais un que ça fera sourire ).
Les vues Outline fournissent un plan du code et certains logiciels ne semblent pas disposer d’une fonction de tri. Et au cas où un jour vous n’auriez pas votre IDE favori sous le nez, ça ne mange pas de pain de fonctionner ainsi.
Que l’on travaille seul à plusieurs, et à plus fortes raison dans ce dernier cas, l’utilisation de notations et conventions est un gage de qualité. Ça rend le travail plus facilement interopérable avec d’autres développeurs, plus facile à relire, plus facile à maintenir.
Ça n’empêchera jamais des bugs ou de sortir du mauvais code mais c’est ça, c’est une autre histoire.
Enfin, j’aimerais terminer cet article en écrivant qu’il a fait l’objet d’une chaîne par le Padawan PHPiste Damien Alexandre. C’était l’occasion de faire une réponse qui passe inaperçue
Ça ne m’empêchera en revanche pas de refiler la patate chaude à NicoDePrendreUnCafé, de tenter d’insuffler de l’activité au blog de Xavier Lacot, de Spipifier Gastero Prod, d’extirper une technique ninja pyjama à remouk et pourquoi pas lire avec attention l’avis pythonien de David Larlet ?
Et just for fun, un petit coup d’électrode à un de mes futurs étudiants, Thierry Poinot.
Si jamais ça ne va pas (contenu pas adapté ou autre), n’hésite pas à me le signaler...
Commentaires & rétroliens
Des … espaces !
Tu dis préférer les espaces aux tabulations, et après tu dis que tu utilises des « tabulation à 2 espaces », tu aimes bien perdre ton lectorat ? :-p
Ah oui, au fait, c’est « Gastero Prod », pas « Gasteroprod » ! :-p
Oui c’est pour voir si vous suivez
très intéressant comme toujours.
deux remarques (1 cent par remarque) :
* tu ne mentionnes pas l’outillage disponible qui permet d’imposer / faciliter l’utilisation de conventions de codage au sein d’une équipe : http://pear.php.net/package/PHP_Beautifier, http://pear.php.net/package/PHP_CodeSniffer
* Joel Spolsky a un point de vue très intéressant sur la notation hongroise. je pense qu’il n’a pas tort du tout : http://www.joelonsoftware.com/articles/Wrong.html
et à bientôt
hello
Pour moi tes recommandations font a peu près consensus et j’utilise les mêmes. Je regrette que les développeurs de php ne préconisent pas quelque chose. L’initiative de PEAR a été très structurante à l’époque de PHP4.
Hi,
Pour ma part, c’est toujours 4 espaces. J’aime pas 2 espaces. (avis subjectif) ça alourdi la lecture du code (surtout en PHP). Je préfère du code aéré, bien espacé. Par contre, quand je suis sur un projet Symfony, j’utilise du 2 espaces pour rester dans les conventions du framework.
Il y a aussi la convention Zend Framework, celle que j’utilise.
Bonne journée.
Les coding standards de PEAR sont quand même présents dans la doc PHP, c’est déjà une bonne piste…
Bonjour,
J’étais du même avis que toi concernant les espaces et les tabulations. Le soucis apparaît dès que tu travailles à plusieurs sur les mêmes fichiers, et que tous n’ont pas les mêmes préférences. Moi, par exemple, je préfère des tabulations avec une taille de 4. Je suppose que lire ton code me paraitrait moins clair.
L’avantage des tabulations, c’est que c’est à l’utilisateur final de décider la manière dont s’afficheront les indentations. C’est finalement la solution que je trouve la plus adaptée. Tu préfères des tabulations de 2 ? Il suffit de paramétrer ton éditeur pour que l’affichage soit à ta convenance, sans pour autant m’empêcher de les afficher avec une taille double.
Non désolé mais les chaînes, je fais pas.
Et puis les conventions de Symfony me conviennent parfaitement !
@Tristan : ça m’est complètement sorti de la thème le PHPBeautifier. À creuser pour moi car jamais utilisé. La démo de Joel est assez convaincante aussi … mais je me vois mal l’utiliser, notamment dans SF qui nettoie tout comme il faut.
@Gilles : subjectif aussi car 4 ça fait trop espacé pour mes yeux. Je rajoute la convention de Zend, honte à moi
@Ghusse : Effectivement pour les tabulations, et sa taille décidée par l’utilisateur … y’aura toujours un inconvénient toutes façons !
@remouk : p’tit joueur ! C’était ma première chaîne, jusqu’à présent j’avais toujours botté en touche et je me suis dis que c’était l’occasion de traiter ça sans que ça soit apparent.
Mes conventions de codage……
Personnellement, j’ai mes petites préférences et tout comme Oncle Tom – qui m’a gentiment refilé cette chaîne[2] – j’ai tendance à appliquer les standards de codage de symfony, que je trouve homogènes et cohérents. Mais ce sont là bien évid…
[...] Et la rumeur se confirme se matin (1h50) en lisant pour la dernière fois mes flux, je tombe sur un article de l’Oncle Tom…Bon pas très original comme article puisque c’est au moins le 10eme que je lis depuis [...]
Chouette article,
Pour ma part … je prends les conventions un peu à droite et à gauche … au lieu de me focaliser sur une seule ! tant que ca reste compréhensible (avec penchant pour la convention hongroise car un prof m’en a fait baver il fût un temps …)
Ensuite ca dépends de quel monde nous venons .. Java boy ou plutôt Scriptoman ou Unix geek …
Aussinon c’est complètement idiot d’utiliser des espaces au lieu de tabs pour l’indentation pour la simple et bonne raison car quand tu te déplaces dans ton code sans souris ( ce qui est souvent le cas des dévelopeurs … ) C’est bien plus simple de sauter de tablulation en tabulation pour mieux comprendre à quel niveau nous nous trouvons …
Certains éditeurs permettent aussi de commenter des lignes de codes commençant par des tabs en mode insert !
Cheers
Mig
Une microrègle dans claroline.
une variable qui contient une liste d’élément portera le nom du conteneur s’il existe mais c’est rare, dans les autres cas, il portera le noms des éléments, mais pas au pluriel. On suffixera le nom de List ou Array pour exprimer le contenu de la variable
Ça devient complexe ces commentaires !
Je crois qu’il faudrait qu’un Français fasse un article sur « tabs » vs « space », des anglais s’y sont essayés, oncle tom si tu veux encore plus de commentaires lance donc un « espace » vs « tabs » !
On voit tout de même que dès qu’on parle un peu de la vie de tous les jours des développeurs, ils sont prompts à répondre !
Allez, je fais une exception à la règle pour toi, Tom. Mais c’est bien parce que NiKo a posté une réponse qui me convient parfaitement ! (comment ça, fainéant ?)
http://lacot.org/blog/2008/07/24/mes-conventions-de-codage.html
Y’aurait de quoi faire un blog tabs vs. space avec tout ça ! Ceci dit j’étais loin de me douter qu’y avait vraiment 2 clans qui s’opposaient comme ça.
Ce que je regrette du coup dans les projets PHP c’est qu’on soit un coup en 2 espaces, 4 espaces, 1 tab … bref difficile de se fixer.
En tous cas vos commentaires sont intéressants, les retours extérieurs aussi. On sent quand même les habitudes
Mes conventions de codage…
Oncle Tom m’a envoyé en douce il y a quelques jours une patate chaude en m’invitant à vous parler de mes conventions de codage. Vaste sujet, et surtout très vite trollesque, de quoi se régaler….
Répondre