racine uZine

Dans la même rubrique
Guide du webmestre et du bidouilleur SPIP
23 septembre 2001
2 juillet 2001
15 juin 2001
 
dimanche 10 juin 2001

Contribuer au développement de SPIP

Quelques règles
par l’équipe de SPIP
 

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 !

 
 
l’équipe de SPIP
Imprimer
format impression
l’équipe de SPIP
23 septembre 2001
 
SPIP
Web indépendant


Problèmes élémentaires de fermeture de boucle
30 juillet 2001, message de Perline
 

Bonjour,
J’ai tenté de changer deux ou trois choses de base, j’ai quelques problèmes, jusqu’à présent, uniquement dans les squelettes,dans le code de base ça a pu aller.
Dès que je veux changer quelque chose aux squelettes, ne serait-ce que la couleur de la premiere URL (c’est dire si pas grand chose), impossible d’afficher, j’ai des messages du genre : BOUCLE_haut : tag fermant manquant ! (par exemple, dans sommaire, quand je change la couleur de
#NOM_SITE_SPIP
en
#NOM_SITE_SPIP

Il est vrai que cette couleur (#E86519) je la connais pas chez moi....

Alors que, avec les squellettes de base le tag semble ne pas manquer, si on change la couleur ou la taille, et pis encore si on met un tableau en tête de fichier, il veut des tags ?

C’est vrai que la plupart des boucles n’ont pas de tag de fermeture, d’ailleurs, alors je me pose les questions :
- pourquoi les boucles ne sont-elles pas fermées ?
- pourquoi ça marche sans fermeture de boucle ?
- pourquoi dès qu’on change le moindre détail insignifiant, là il veut un tag de fermeture de boucle ?

Comme j’ai absolument besoin de mettre un en-tête différent (couleurs, tableaux, etc.) j’aimerais beaucoup et en urgence une solution, outre le fait que ça me titille cette histoire de boucles pas fermées qui marchent quand même...
Merci

Autre chose
le logo à télécharger pour rubrique, je n’arrive pas à le cahnger (parfois, pas tourjous).
J’efface, je recharge l’autre mais il garde le précédent.

Enfin : commnet fait-on pour mettre des url cliquables dans le texte (ou sinon, hors du texte) sans les liens de syndication ?
Et dans les liens de syndication, commnet fait-on pour avoir le nom du site, et qu’il soit cliquable (avec une url, mais qu’il serait impossible de mettre en toute lettre car pas claire) ?

Répondre
> Problèmes élémentaires de fermeture de boucle, 30 juillet 2001

Autre chose le logo à télécharger pour rubrique, je n’arrive pas à le cahnger
(parfois, pas tourjous). J’efface, je recharge l’autre mais il garde le précédent.

C’est à cause du cache du navigateur : comme le fichier créé sur le serveur
porte toujours le même nom pour la même rubrique, le browser pense que
son contenu n’a pas changé. Il suffit de recharger la page si le logo apparaît erroné.

Enfin : commnet fait-on pour mettre des url cliquables dans le texte (ou sinon,
hors du texte) sans les liens de syndication ?

Dans un texte, il suffit d’utiliser les raccourcis typographiques : par
exemple [uzine 2->http://uzine.net/] donne : uzine 2.

Et dans les liens de syndication,
commnet fait-on pour avoir le nom du site, et qu’il soit cliquable (avec une url,
mais qu’il serait impossible de mettre en toute lettre car pas claire) ?

Essaie quelque chose du genre <A HREF="#URL_SITE">#NOM_SITE</A>

Antoine.

Répondre
> > Problèmes élémentaires de fermeture de boucle, Perline, 3 août 2001

Merci de ton aide, effectivement, c’est impec.
Cela dit je n’ai trouvé nulle part où sont les raccourcis typographiques (s’il en existe d’autres), bien que j’aie tout imprimé, en tous cas je crois.

Quant aux boucles... Mea culpa.

On ne se méfie jamais assez des automatismes, moi qui les annule systématiquement : dans Dreamweaver était cochée l’option de rectification automatique des tags...
Comme il ne comprenait pas, il rectifiait à chaque changement !
Une catastrophe. Et en plus il rectifie aussi les mises en page (tabulations, etc.)

Bref, faites savoir qu’il faut s’en méfier...

Cela dit, si certains ont des vélléités de testeur critique, je veux bien leur passer l’url.

Mais pas avant le 19, avant je suis en

Répondre


Probleme d’affichage des tableaux
23 juillet 2001, message de Patrick Dubois
 

Lorsque l’on cree un tableau en debut d’article, celui-ci etant tronque lors
de l’affichage à la une, il se produit un melange avec le reste de la page, et
le lien "lire la suite" s’affiche dans le tableau. Le tableau n’est probablement
pas ferme correctement et se poursuit jusqu’au prochain tag

rencontré.

Répondre


> Gestion des images
10 juillet 2001, message de Un graphiste peu bidouilleur
 

Système génial, tout ça, tout ça… Si je puis me permettre une suggestion pour une amélioration future, une meilleure gestion des images serait un plus appréciable :

- pourquoi Spip renomme-t-il les images téléchargées ?
- pourquoi ne peut-on utiliser un code #IMAGE comme l’on utilise le code #TEXTE ?

Impossible (?) actuellement d’afficher en première page l’image associée au dernier article posté. On ne peut afficher que le texte.

Bravo en tout cas pour ce superbe outil !

Répondre