Si vous voulez contribuer à la programmation de SPIP,
l’idée la plus importante à retenir est la suivante : vous arrivez sur
un projet qui est déjà fonctionnel. Ce projet est muni
d’un ensemble de règles qui, toutes arbitraires qu’elles
peuvent paraître, assurent sa cohérence. Ces règles n’ont
pas besoin d’être énoncées explicitement pour exister :
certaines sont clairement visibles après un examen plus ou
moins détaillé du code, et les règles tacites doivent être
respectées au même titre que les autres.
Il est formellement conseillé de bien suivre ces règles.
Ce respect n’a pas à être lié ou non à vos goûts personnels :
il permet de garder sa cohérence et son unité au projet, et de
le conserver aussi lisible qu’il l’était auparavant. N’oubliez
pas que d’autres personnes que vous sont amenées à lire, comprendre,
voire modifier votre code.
Par exemple, il est évident que les fonctions SPIP sont écrites
sous la forme ma_fonction(). Dans le cadre de ce projet, il
serait donc parfaitement déplacé d’ajouter des fonctions
en les écrivant MaFonction() - même si dans l’absolu cette
forme n’est pas plus critiquable que l’autre.
Tout ceci n’empêche pas évidemment de critiquer une règle
et d’en proposer une meilleure, le cas échéant. N’hésitez
pas à le faire ; mais il doit y avoir de véritables raisons
à cela.
Enfin, tout règle souffre des exceptions. Mais celles-ci
doivent avoir une véritable justification, non uniquement
la paresse du programmeur ; elles doivent être le plus rares
possible. Notamment, garder à l’esprit que le « provisoire »
a souvent tendance à devenir définitif quand personne n’a
envie de le corriger ; or il est logique et juste que tout programmeur
soit responsable de la finition de son propre code, mais non
de celui des autres.
Règles de présentation et d’écriture
Les règles qui suivent sont communes à un nombre plus ou
moins grand de langages de programmation : au minimum
tous les langages présentant une syntaxe similaire à PHP
(c’est-à-dire, outre PHP lui-même, C, C++, Java....).
Ces règles sont communément acceptées, de façon aussi
naturelle que les règles de présentation et de typographie
d’un texte en langage naturel ; d’ailleurs elles sont
fréquemment similaires.
Présentation
Le code doit être espacé et indenté de manière à mettre
en valeur sa structure et la séparation entre les différents
blocs logiques (fonctions notamment). L’espacement et
l’indentation doivent être suffisants pour rendre la structure
compréhensible dès le premier regard ; ils ne doivent
pas être excessifs. On doit y apporter le même soin qu’à la
division en paragraphes d’un texte en langage naturel.
L’indentation sera faite de préférence avec le caractère
de tabulation. Cela permet de choisir librement la profondeur
d’indentation dans les options de son éditeur de texte, tout
en n’imposant pas ce choix aux autres développeurs.
Tout bloc contenu à l’intérieur d’une paire d’accolades
sera indenté d’une et une seule tabulation. De même, récursivement,
pour les sous-blocs : ajout d’une et une seule tabulation
supplémentaire à chaque entrée dans un niveau de profondeur
supplémentaire. Cette règle vaut bien aussi pour la déclaration
de fonctions.
Le code qui ne fait pas partie d’une fonction ne doit
pas être indenté.
L’utilisation des transitions PHP-HTML (<?php et ?>)
doit être minimisée. L’éviter lors qu’il s’agit
d’afficher uniquement de petits morceaux de HTML. Ne pas oublier
qu’un petit morceau de code PHP inséré au milieu d’un océan
de HTML est invisible sans un examen très attentionné.
Typographie
Lors de l’utilisation de parenthèses ou de crochets,
il ne faut pas laisser d’espace après la parenthèse ouvrante
ni avant la parenthèse fermante.
Lors de l’utilisation d’opérateurs binaires (+, =, *, AND, ...),
il faut laisser un espace de part et d’autre de l’opérateur.
Exception manifeste dans cette phrase, où les opérateurs sont
mentionnés et non utilisés en tant que tels.
Les opérateurs unaires (!, ...) doivent être collés au paramètre
auquel ils s’appliquent.
Par convention, lors d’un appel de fonction, il n’y a pas d’espace
devant la parenthèse ouvrante : « f($x) » et
non « f ($x) ».
A contrario, et pour bien distinguer, on laisse un espace devant
la parenthèse quand il s’agit d’une structure de contrôle
intégrée au langage : « if (!$x) » et non « if(!$x) ».
Les virgules et points-virgules sont suivis mais non précédés
d’un espace.
Règles de programmation
Réfléchir
Avant de programmer une nouvelle fonctionnalité, réfléchir...
méthodes et algorithmes utilisés pour l’implémentation :
légèreté, performance, robustesse (ne pas hésiter à faire quelques calculs grossiers pour valider
les choix) ;
adéquation au projet : portabilité, sécurité, souplesse ;
implications sur les autres fonctionnalités : modifications
et ajouts à faire sur les fonctionnalités existantes ;
place « naturelle » pour cette fonctionnalité dans le projet :
en matière d’interface, de fichiers...
Ne pas négliger la factorisation ou mise en commun du code
(par des fonctions, notamment dans des fichiers à inclure).
Eviter par contre le plus possible les fichiers inclus
contenant du code hors fonctions (sauf lorsque c’est « naturel »
et voulu).
Nommer
Variables et fonctions :
Quel que soit le projet, le nommage doit rester homogène pour que
le code soit facile à lire. Ainsi, sous SPIP, les noms de variables
et de fonctions seront en minuscules ; les noms composés, de la
forme variable_composee.
D’une manière générale, les noms seront ni trop brefs, ni trop longs ;
ile seront suffisamment explicites. Cette règle est particulièrement
importante pour les variables globales, qui peuvent être partagées
entre plusieurs fichiers et de nombreuses fonctions. Pour les variables locales
(i.e. à une fonction), la règle est plus souple. Notamment,
on peut employer des variables d’une lettre, par exemple pour obtenir
des expressions plus compactes. Remarquer
que dans tous les langages de programmation, un certain nombre de
lettres sont par tradition associées à certains usages (exemples :
$i, $j pour des compteurs de boucles, $n pour un dénombrement, $t
pour un instant ou une durée en secondes...). Ne pas détourner
ces conventions permet à vos lecteurs d’être plus vite dans le bain.
Fichiers :
Pour des raisons historiques, les fichiers à inclure dans l’espace
public seront appelés inc-fichier.php3. Dans l’espace privé, ce
sera ecrire/inc_fichier.php3 (noter le tiret bas à la place du tiret normal).
Les fichiers de l’espace public appelés par redirection HTTP depuis
l’espace privé sont appelés spip_fichier.php3. Tous les autres fichiers
ont un nom qui ne commence ni par "inc", ni par "spip".
Tester
Une fois une modification importante apportée, il est bon de
la tester soi-même, sans attendre que quelqu’un d’autre le fasse
à sa place. Dans le cadre de SPIP, cela veut dire vérifier que
le programme marche de manière correcte sur un certain nombre
d’hébergeurs (par exemple : Altern, Free...) et de configurations
(par exemple : différentes versions de PHP, de MySQL, restriction
plus ou moins grande des droits d’accès aux répertoires...) ;
mais aussi qu’un certain nombre de situations parmi les plus
courantes (dans le cas d’une
interface graphique notamment) sont traitées correctement.
Partager vos modifications
Une fois que vous êtes satisfait de votre modification du code, il est grand temps
d’en parler avec les autres développeurs de SPIP, et de voir s’il mérite d’être intégré à la distribution officielle de SPIP... Rendez-vous sur la liste de
diffusion spip-dev. A bientôt !
