És molt aconsellable seguir aquestes normes. Aquest respecte no pot estar subjecte als vostres gustos personals: així es guarda la coherència i la unitat del projecte, així com també conserva la llegibilitat que tenia als inicis. No oblide tampoc que altres persones estan convidades a llegir, comprendre, vore i modificar el vostre codi.
Per exemple, és evident que les funcions SPIP estan escrites baix la forma ma_fontion(). Al quadre d’aquest projecte, estarà doncs fora de lloc afegir funcions escrivint-les MaFonction() - tanmateix aquesta forma no és més criticable que l’altra.
Tot açò no impedeix evidentment criticar una norma i proposar una alternativa millor, arribat el cas. No dubteu en fer-ho; però han d’existir veritables raons per a que tal cosa passe.
En fi, tota norma té també excepcions. Però ha d’haver-hi una veritable raó que la justifique, no únicament l’opinió del programador; han de ser el més rares possibles. Especialment, conserveu l’esperit que allò que és "provisional" té sovint tendència a esdevenir definitiu quan cap persona te ganes de corregir-ho; ara bé, és just i lògic que tot programador siga responsable de la finalització del seu propi codi, però no del codi dels altres.
Normes de presentació i d’escriptura
Les normes que són comunes en un nombre més o menys gran de llenguatges de programació: com a mínim tots els llenguatges presenten una sintaxi similar a PHP (és a dir, apart de PHP, C, C++, Java...).
Aquestes regles són comunment acceptades, de forma tan natural com les normes de presentació i de tipografia d’un text escrit en llenguatge humà; els quals són freqüentment similars.
Presentació
- El codi ha de ser espaiat i indentat de manera per valorar la seua estructura i la separació entre els blocs lògics (funcions especialment). L’espaiament i la indentació han de ser suficients per a obtindre una estructura comprensible des de la primera ullada; no han de ser excessives. S’ha de ficar la mateixa cura que a la divisió en paràgrafs d’un text en llenguatge natural.
- La indentació se farà preferentment amb el caràcter de tabulació. Així es permetrà triar lliurement la profunditat d’indentació a les opcions del seu editor de textos, sempre sense imposar aquesta tria als altres desenvolupadors.
- Tot bloc contingut a l’interior d’un parell de claus serà indentat d’una i una sola tabulació. De la mateixa manera, recursivament, per als subsblocs: afegir una sola tabulació suplementària per cada entrada de nivell de profunditat suplementari. Aquesta norma val també per a la declaració de funcions.
- El codi que no és part d’una funció no ha de ser indentat.
- L’ús de les transicions PHP-HTML (<?php i ?>)
ha de ser reduït. Evitar-lo si es tracta només d’afegir petits trossos d’HTML. No oblidar que un trosset de codi PHP inserit al mig d’un oceà d’HTML és invisible sense un examen molt detallat.
Tipografia
- Quan s’utilitzen els parèntesis o claudàtors, no cal deixar un espai després del parèntesi que obre ni tampoc abans del que tanca.
- Quan s’usen operadors binaris (+, =, *, AND, ...), cal deixar un espai als dos costats de l’operador, [així: Expressió1 = Expressió2] Excepció és aquesta frase on els operadors són mencionats però no han estat emprats com a tals.
- Els operadors unaris (!, ...) han de ser pegats al paràmetre al qual s’apliquen.
- Per convenció, quan se crida a una funció, no hi ha cap espai davant del parèntesi que obre: "f($x)" i no "f ($x)". Al contrari, i per distingir-ho bé, es deixa un espai davant el parèntesi quan es tracta d’una estructura de control integrada al llenguatge: " if (!$x)" i no " if(!$x)".
- Les comes i els punts i coma són seguits però no precedits d’un espai.
Normes de programació
Reflexionar
Abans de programar una nova funcionalitat cal reflexionar...
- mètodes i algoritmes emprats per la implementació: lleugeresa, performance, robustesa (no dubtar de fer alguns càlculs grossers per validar les coses);
- adequació al projecte: portabilitat, seguretat, flexibilitat;
- implicacions sobre les altres funcionalitats: modificacions i afegitons a fer sobre les altres funcions existents;
- lloc "natural" per aquesta funció dins del projecte: en matèria d’interfície, de fitxers...
No oblidar la factorització o posada en comú del codi (per les funcions, particularment en els fitxers a incloure). En canvi, haurem d’evitar mentre sigui possible els fitxers inclosos que continguin codi fora de les funcions (excepte quan siga "natural" i desitjat).
Anomenar
- Variables i funcions :
Qualsevol que siga el projecte, la nomenclatura ha de restar homogènia per a que el codi siga de fàcil lectura. Així, a SPIP, els noms de les variables i de les funcions seran en minúscules; els noms compostos, de la forma variable_composta.
D’una manera general, els noms no seran ni massa llargs ni massa breus; seran prou explícits. Aquesta regla és particularment important per a les variables globals, que poden ser comunes a varis fitxers i a nombroses funcions. Per això les variables locals (i.e. a una funció), la norma és flexible. Hem de puntualitzar que es pot emprar les variables d’una lletra per exemple per obtindre expressions més compactes. També cal remarcar que a tots els llenguatges de programació, un cert nombre de lletres són per tradició associades a certs usos (exemples: $i, $j per a comptadors als bucles, $n per a una enumeració, $t per un instant o una durada de temps en segons...). No apartar-se massa de les convencions permet als vostres lectors endinsar-se més aviat en l’assumpte que tracteu.
- Fitxers :
Per raons històriques, els fitxers que s’han d’incloure a l’espai públic són anomenats inc-fichier.php. A l’espai privat, aquest serà ecrire/inc_fichier.php (Adoneu-vos hi ha un guió baix en comptes del guió normal). Els fitxers de l’espai públic cridats per redirecció HTTP des de l’espai privat són anomenats spip_fichier.php. Tots els altres fitxers tenen un nom que no comença per "inc", ni per "spip".
Provar
Una vegada una modificació important ha estat aportada, és una bona idea provar-la un mateixa, sense esperar que algú ho faça per vosté. En aquest contexte de l’SPIP, allò que ens indica si el programa funciona correctament és que es pot emprar en cert nombre de servidors web (per exemple: Altern, Free...) i amb diverses configuracions (per exemple: diferents versions de PHP, de MySQL, restriccions més o menys gran dels drets d’accés als directoris...); d’aquesta manera un nombre de situacions entre les més corrents (en particular al cas de la interfície gràfica) són tractades correctament.
Compartir les seues modificacions
Un cop que estiga satisfet amb la modificació del codi, és el moment de parlar-ne amb els altres desenvolupadors d’SPIP, i vore si la seua modificació del codi mereix ser incorporada a la distribució oficial d’SPIP... Es pot dirigir a la llista de correu spip-dev. Fins aviat!