Si consiglia formalmente di seguire queste regole. Questa osservanza deve essere svincolata dai gusti personali: essa permette di mantenere l’omogeneità e l’unità al progetto e di conservarlo leggibile quanto lo era in precedenza. Non dimenticate che altre persone devono leggere, comprendere nonché modificare il vostro codice.
Per esempio, è evidente che le funzioni SPIP sono scritte nel formato mia_funzione(). Nel quadro di questo progetto, sarebbe quindi fuori luogo aggiungere funzioni scritte come MiaFunzione() - anche se in assoluto questa forma non sia meglio o peggio dell’altra.
Tutto ciò non impedisce comunque di muovere critiche a una regola e di proporne una migliore, se necessario. Non esitate a farlo; tuttavia, ci devono essere ragioni fondate per fare ciò.
Infine, ogni regola ha le sue eccezioni. Ma queste devono avere una giustificazione accettabile, non dipendere dal capriccio del programmatore; esse devono essere più rare possibili. In particolare, tenete a mente che il "provvisorio" tende spesso a diventare definitivo quando nessuno ha voglia di correggerlo; ora, è logico e giusto che ogni singolo programmatore sia responsabile della rifinitura del proprio codice, ma non di quello di un altro.
Regole di presentazione e di scrittura
Le regole seguenti sono comuni a un numero più o meno grande di linguaggi di programmazione: almeno tutti i linguaggi che hanno una sintassi simile al PHP (cioè, oltre al PHP stesso, C, C++, Java....).
Queste regole sono comunemente accettate, in maniera così naturale come le regole di presentazione e tipografiche di un testo in linguaggio naturale; d’altronde esse sono spesso simili.
Presentazione
- Il codice deve essere spaziato e indentato in modo da evidenziare la sua struttura e la separazione tra i diversi blocchi logici (soprattutto funzioni). La spaziatura e l’indentazione devono essere sufficienti per rendere comprensibile la struttura già a colpo d’occhio; non devono essere eccessive. Si deve avere la medesima cura che si ha nel dividere in paragrafi un testo in linguaggio naturale.
- L’indentazione sarà fatta preferibilmente con il carattere di tabulazione. Ciò permette di scegliere liberamente la profondità di indentazione nelle opzioni del proprio editor di testi, pur non imponendo questa scelta agli altri sviluppatori.
- Qualsiasi blocco contenuto all’interno di un paio di parentesi graffe verrà indentato da una e una sola tabulazione. Lo stesso si applica, ricorsivamente, ai sotto-blocchi: aggiunta di una sola e unica tabulazione supplementare ad ogni riga in un livello di profondità supplementare. Questa regola vale anche per la dichiarazione delle funzioni.
- Il codice che non fa parte di una funzione non deve essere indentato.
- L’utilizzo delle transizioni PHP-HTML (<?php e ?>) deve essere ridotto al minimo. Evitarlo quando si tratta di visualizzare unicamente piccoli pezzi di HTML. Non dimenticare che un piccolo pezzo di codice PHP inserito in mezzo a un oceano di HTML è invisibile senza un esame approfondito.
Tipografia
- Durante l’utilizzo di parentesi tonde o quadre non si deve lasciare spazio dopo la parentesi aperta né prima della parentesi chiusa.
- Durante l’uso di operatori binari (+, =, *, AND, ...), si deve lasciare uno spazio prima e dopo l’operatore. Eccezione manifesta in questa frase, in cui gli operatori vengono menzionati e non utilizzati in quanto tali.
- Gli operatori unari (!, ...) devono essere incollati al parametro al quale si applicano.
- Per convenzione, in caso di chiamata a una funzione non vi è alcuno spazio davanti la parentesi aperta: " f($x) " e non " f ($x) ". Al contrario, e al fine di una netta distinzione, si lascia uno spazio davanti alla parentesi quando si tratta di una struttura di controllo integrata nel linguaggio: " if (!$x) " e non " if(!$x) ".
- Le virgole e i punti e virgola sono seguiti ma non preceduti da uno spazio.
Regole di programmazione
Riflettere
Prima di programmare una nuova funzionalità, meditare...
- metodi e algoritmi utilizzati per l’implementazione: leggerezza, performance, robustezza (non esitare a fare calcoli approssimativi per convalidare le scelte);
- adeguatezza al progetto: portabilità, sicurezza, flessibilità;
- implicazioni sulle altre funzionalità: modifiche e aggiunte da fare sulle funzionalità già presenti;
- luogo "naturale" per questa funzionalità nel progetto: nell’ambito dell’interfaccia, dei file...
Non trascurare la fattorizzazione o la condivisione del codice (per le funzioni, soprattutto nei file da includere). Evitare di contro il più possibile i file inclusi contenenti codice al di fuori delle funzioni (eccetto quando è "naturale" e voluto).
Attribuire nomi
- Variabili e funzioni:
Indipendentemente dal progetto, l’attribuzione di nomi deve rimanere omogenea affinché il codice sia facile da leggere. Perciò, in SPIP, i nomi delle variabili e delle funzioni saranno in lettere minuscole; i nomi composti nel formato variabile_composta.
In generale, i nomi non saranno né troppo corti né troppo lunghi; saranno sufficientemente espliciti. Questa regola è particolarmente importante per le variabili globali, che possono essere condivise tra diversi file e numerose funzioni. Per le variabili locali (cioè, a una funzione), la regola è meno rigida. Soprattutto, si possono utilizzare variabili di una sola lettera, per esempio per ottenere espressioni più compatte. Notare che in tutti i linguaggi di programmazione un certo numero di lettere è tradizionalmente riservato ad alcuni usi (per esempio: $i, $j per i contatori dei cicli, $n per un conteggio, $t per un istante (tick) o una durata in secondi...). Non deviare da queste convenzioni permette ai vostri lettori di entrare più speditamente nel codice.
- File:
Per ragioni storiche, i file da includere nell’area pubblica saranno chiamati inc-fichier.php3. Nell’area riservata saranno chiamati ecrire/inc_fichier.php3 (notare l’underscore al posto del trattino normale). I file dell’area pubblica chiamati tramite reindirizzamento HTTP dall’area riservata sono chiamati spip_fichier.php3. Tutti gli altri file hanno un nome che non comincia né con "inc" né con "spip".
Testare
A seguito di una modifica rilevante è bene testarla da sé, senza attendere che qualcun altro lo faccia al proprio posto. Nel quadro di SPIP, ciò significa verificare che il programma funzioni correttamente su un certo numero di hoster (per esempio: Altern, Free...) e di configurazioni (per esempio: diverse versioni di PHP, di MySQL, restrizioni più o meno grandi dei diritti di accesso alle cartelle...); ma significa anche che un certo numero di situazioni tra le più frequenti (in particolare nel caso di un’interfaccia grafica) siano trattate correttamente.
Condividere le vostre modifiche
Quando sarete soddisfatti delle vostre modifiche al codice è giunta l’ora di parlarne con gli altri sviluppatori di SPIP, e di vedere se esse meritano di essere integrate nella distribuzione ufficiale di SPIP... Recatevi alla lista di diffusione spip-dev. A presto!