[ar] [ast] [bg] [br] [ca] [co] [cpf] [cs] [da] [de] [en] [eo] [es] [eu] [fa] [fon] [fr] [gl] [id] [it] [ja] [lb] [nl] [oc] [pl] [pt] [ro] [ru] [sk] [sv] [tr] [uk] [vi] [zh] Espace de traduction

Télécharger

Contribuer au développement de SPIP

Quelques règles valables pour les versions jusqu’à SPIP 1.7.2

Juin 2001 — mis à jour le : Mars 2009

Toutes les versions de cet article :

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 ; ils 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.php. Dans l’espace privé, ce sera ecrire/inc_fichier.php (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.php. 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 !


Voir le squelette de cette page Site réalisé avec SPIP | Espace de traduction | Espace privé