Arborescence de fichers

Rien de pire qu'un tas de fichiers en désordre. Faites des répertoires, des catégories, toujours et encore. Mais pour organiser cette arborescence, faites-vous des règles, et tenez-vous y. Si vous êtes en équipe, faites-les respecter à tout prix (même celui de passer pour le casse-bonbons de service). Au moment où l'on devra corriger un bug en urgence dans un fatras de 340 fichiers, tout le monde sera bien content si une certaine logique sous-tend encore l'organisation de ces 340 fichiers.

Noms de fichiers

Quelque chose d'encore plus important, c’est la nomenclature des noms de fichiers. Vous êtes vous déjà posé la question sur comment vous nommez vos fichiers ? En français ? En anglais ? En minuscule ? En majuscule ? C'est fondamental.

Acceptez les espaces dans les noms de fichiers, ou l'anarchie concernant les minuscules et les majuscules, et vous allez droit à la catastrophe. Les fichiers ne sont plus reconnus sur certains systèmes ou lors d'un transfert FTP. L’autre gros problème est pour les nouveaux programmeurs : comment peut-il s’y retrouver ? Un coup il y a un _, un autre coup non, en gros il faut apprendre par cœur le nom de chaque fichier ! Le nouveau programmeur c'est aussi vous, quand vous revenez sur un projet après plusieurs mois...

D'où l'importance de fixer une convention de nommage (nomenclature) simple, et de s'y tenir strictement et rigoureusement. Pourquoi simple ? Parce qu'il est inutile de complexifier inutilement ce qui n'a pas besoin de l'être : KISS (Keep It Simple, Stupid). Pourquoi stricement ? Parce qu'il y toujours, inexplicablement, des personnes ou des moments avec lesquels cette nomenclature, pour simple qu'elle soit, aura tendance à ne pas être suivie. Par esprit de contradiction, parce qu'elle entre en conflit avec des habitudes, parce qu'on a envie, de temps en temps, voire tout le temps, de nommer ses fichiers au gré de son humeur. Et c'est là, très exactement, que les ennuis commencent...

Quand on parle des noms de fichiers, on parle aussi... des noms de répertoires, bien sûr !

Noms de fonctions

Continuons du plus grand au plus petit : à l'intérieur d'un fichier... On indente son code, bien sur.

Mais surtout on suit aussi une nomenclature pour les noms de fonctions. Histoire de ne pas être obligé de regarder à chaque fois si "do this" s'écrit DoThis(), do_this() ou dothis().

A cet égard, le langage PHP, de par ses origines historiques (mélange de Perl et de C) est un cauchemar : les fonctions qui traitent les tableaux commencent souvent par array_, mais certaines commencent juste par a, et d'autres ne sont tout simplement pas identifiables : sort(), par exemple. Mais le sommet est atteint par une paire de fonctions jumelées : html_entity_decode() est la fonction contraire de htmlentities(). La première a été créée bien après la seconde, et on a réussi à ne prendre en compte ni la jointure/séparation des mots, ni le singulier/pluriel, ni la présence/absence d'un verbe d'action ! Un nommage intelligent aurait été htmlentities_decode() pour la première fonction. Cela aurait eu l'avantage de respecter la réalité (on encode/décode en général plus d'une entité, donc le singulier n'a aucune raison d'être), et de respecter le nommage de deux autres fonctions de role approchant, qui s'appellent respectivement htmlspecialchars() et htmlspecialchars_decode()... Au lieu de cela, les programmeurs doivent apprendre par coeur le nom des fonctions, ou passer (perdre, donc) leur temps sur fr.php.net ou un autre site de référence pour vérifier l'ortographe de leur fonction. Ou se faire leurs petits alias à eux, ce qui présent toujours des risques lors de la communication entre programmeurs...

Et lorsque vous faites un programme, respecter une nomenclature de noms de fonctions vous évite biens des efforts de... documentation ! Un nom de fonction devrait comprendre un verbe d'action et le ou les objets sur lesquel porte cette action.

Noms de variables

Les variables gagnent aussi à suivre une certaine nomenclature. Ne serait-ce que parce que certaines sont publiques...

Ou au moins une certaine logique. Parce que des noms de variables limpides facilitent la relecture du code, et évitent certaines mésaventures.

N'appelez par une variable quelconque i, j ou index, non seulement ce n'est pas parlant, mais c'est un nom utilisé par les index des boucles : on s'attend donc à ce qu'elle ait ce rôle et soit utilisée très localement, et elle risque d'être écrasée un peu plus loin par une boucle qui tournera sur une variable portant ce nom... Si c'est effectivement un index, préférez type_id : user_id, article_id, etc...

Des nomenclatures existent, plus ou moins complexes, plus ou moins officielles (notation hongroise, ...). Cet article développe plus avant l'intérêt de les respecter dans le développement d'un projet.

Témoignage

Pour finir, un petit témoignage, que nous devons à Vianney Lecroart mais que j'ai personnellement vécu d'innombrables fois :

À mes débuts à Nevrax, pour le développement d’un MMORPG Windows/Linux, j’avais proposé une règle très simple suivant justement le principe KISS, en partant du principe que plus les règles seront simples, plus il y a de chance que les gens la connaitront et la suivront.

* Règle 1: Nommage de tous les fichiers et tous les répertoires : uniquement des caractères alphanumériques en minuscule, les mots étant séparés par des _. Pour les geeks, on peut résumer ça en a-z0-9_+

* Règle 2: pas de règle 2…

On peut difficilement faire plus simple, ça évitait tous les problèmes des espaces, des majuscules et des caractères bizarres. Bien que cette règle soit simple et rabâchée depuis le début du projet, un certain nombre de programmeurs n’arrivaient pas (ou ne voulaient pas) la suivre et mettaient des noms de fichiers qui ne suivaient pas cette règle. Mais le pire a été avec les graphistes, designers, sound designers… Ils ne voulaient pas se plier à cette règle et voulaient continuer à faire comme ils faisaient avant (c’est à dire sans règles, au gré des humeurs). Pour éviter des conflits trop violents, il a été décidé de n’appliquer la règle que pour le code source et ce fut une belle erreur. Pendant des années on a dû ajouter des bouts de code (rustines) dans les tools, sous Linux uniquement, pour gérer des cas particuliers dans les noms fichiers et répertoires parce qu’ils ne voulaient pas se plier à cette règle simple. Il est même arrivé de devoir mettre des rustines dans des outils qui fonctionnaient parfaitement bien depuis 4 ans parce qu’une personne avait trouvé un nouveau moyen fun de nommer les répertoires qui cassait le peu de logique qui restait dans l’arborescence des données.

Autant je comprends que les gens soient réticents à suivre des règles complexes ou qui n’ont pas de sens. Mais je ne comprends toujours pas pourquoi autant de personnes ont protesté si fortement contre une règle simple qui aurait mis de la discipline dans le source control et aurait rendu la vie tellement plus simple à tous.