Stile e Sintassi
La pagina seguente descrive le regole per scrivere codice quando si sviluppa CodeIgniter.
Tabella dei Contenuti
- Formato dei file
- Tag di Chiusura di PHP
- Nomi delle Classi e dei Metodi
- Nomi delle Variabili
- Commenti
- Costanti
- TRUE, FALSE e NULL
- Operatori Logici
- Confrontare Valori di Ritorno e Typecasting
- Debugging del Codice
- Spazi Bianchi nei Files
- Compatibilità
- Nomi delle Calssi e dei File Utilizzando Parole Comuni
- Nome delle Tabelle del Database
- Un File per ogni Classe
- Spazzi Bianchi
- Interruzioni di Linea
- Indentatura del Codice
- Parentesi e Spazzi
- Localizzare il Testo nel Pannello di Controllo
- Metodi e Variabili Private
- Errori PHP
- Tags di Apertura Abbreviati
- Un Comando per Linea
- Stringhe
- Queries SQL
- Argomenti di Default delle Funzioni
- Sovrapposizione dei Parametri dei Tag
File Format
I file dovrebbero essere salvati con il formato Unicode (UTF-8). Il BOM (Byte Order Mark) non dovrebbe essere utilizzato. Diversamente da UTF-16 e UTF-32, in un file UTF-8 non ci sono byte che indicano questo formato, e il BOM potrebbe avere effetti negativi in PHP in fase di output, impedendo all'applicazione di configurare correttamente le proprie headers. Le interruzioni di linea Unix dovrebbero essere utilizzate (LF).t
Di seguito come configurare queste impostazioni nei più comuni editor di testo. Queste indicazioni potrebbero essere diverse per altri editor per i quali si rimanda alla loro documentazione.
TextMate
- Aprire Application Preferences
- Selezionare Advanced, e successivamente il tab "Saving"
- In "File Encoding", selezionare "UTF-8 (recommended)"
- In "Line Endings", selezionare "LF (recommended)"
- Opzionale: Seleziona "Use for existing files as well" se si desidera modificare le terminazioni di linea aperti con le nuove preferenze.
BBEdit
- Aprire Application Preferences
- Selezionare "Text Encodings" sulla sinistra.
- In "Default text encoding for new documents", selezionare "Unicode (UTF-8, no BOM)"
- Opzionale: In "If file's encoding can't be guessed, use", si scelga "Unicode (UTF-8, no BOM)"
- Selezionare"Text Files" sulla sinistra.
- In "Default line breaks", selezionare "Mac OS X and Unix (LF)"
Tag di Chiusura PHP
I Tag di chiusura nei documenti PHP è un elemento opzionale. Comunque, se usato, ogni spazio bianco che è presente successivamente al tag di chiusura, inserito dal programmatore, oppure l'utente, o una applicazione FTP, può causare un output inaspettato, errori PHP, o, se questi ultimi sono disabilitati, delle pagine bianche. Per questa ragione, tutti i file PHPdovrebbero TRALASCIARE i tag di chiusura, al suo posto è preferibile usare un blocco di commento che identifica la chiusura del file e la sua posizione rispetto alla root dell'applicazione. Questo permette di idenficare che un file è completo e non spezzato.
Nome delle Classi e dei Metodi
I nomi delle Classi dovrebbero avere sempre l'iniziale maiuscola, ed il nome del costruttore dovrebbe essere sempre dello stesso nome. Le parole multiple dovrebbero essere separate da un uderscore e non con il metodo CamelCased. Tutti gli altri metodi della classe dovrebbero essere interamente in minuscolo ed il nome dovrebbe indicare chiaramente la loro funzionalità, preferibilmente includendo un verbo. Cercate di evitare nomi troppo lunghi e prolissi.
Si noti che il nome della Classe e del suo costruttore devo essere identici:
Esempi di nomi corretti e incorretti:
Nomi di Variabili
Le linee guida per i nomi delle variabili sono molto simili a quelle utilizzate per i metodi. Cioé, le variabili dovrebbero contenere solo lettere minuscole, usare l'uderscore per separara una parola da un'altra, ed utilizzare un nome indicativo che identifichi il contenuto e lo scopo. Nomi molto corti, non parole, vengono utilizzati sono cicli for().
Commenti
In generale, dovrebbe essere abbondantemente commentato. Questo non solo aiuta a descrivere il flusso e lo scopo del codice per i programmatori meno esperti, ma può risultare prezione quando si ritorna sul codice dopo alcuni mesi. Non c'è un formato specifico per i commenti, ma se ne raccomanda i seguenti.
Lo stile dei commenti DocBlock precedente la dichiarazione della Classe e dei Metodi possono essere raccolti dagli IDEs:
Utilizza il commento a linea singola all'interno del codice lasciando una linea biancha tra i blocchi di commenti lunghi e il codice.
Costanti
Le Costanti segueno le stesse linee guida delle variabili, eccetto per il fatto che dovrebbero essere scritte tutte maiuscole. CodeIgniter quando opportuno utilizza sempre le costanti, esempio SLASH, LD, RD, PATH_CACHE, etc.
TRUE, FALSE, and NULL
Le parole chiave TRUE, FALSE, e NULL dovrebbero essere sempre scritte in maiuscolo.
Operatori Logici
L'uso di || è sconsigliato soprattutto per la confusione che genere a livello di output (potrebbe essere facilmente confuso con un 11 per esempio). && è preferito al'AND, ma entrambi sono accettati, il ! deve essere seguito e procededuto da uno sapzio.
Confrontare i Valori di Ritorno ed il Typecasting
Alcune funzioni PHP restituiscono il valore FALSE quando falliscono, ma potrebbero avere anche un valore di ritono valido com e "" oppure 0, i quali potrebbero essere interpretati come equivalenti di FALSE. E' necessario essere espliciti per comparare, in un situazione di condizione, il tipo di variabile quando si utilizzano i valori di ritorno per essere sicuri che il valore che ci è stato restituito è quello che ci aspettavamo, e non un valore equivalente.
Utilizzate lo stesso rigore nel controllare le proprie variabili di ritorno. Usate === e !== quando necessario.
Per maggiori informazioni si consiglia di leggere questo documento sul typecasting. Typecasting ha un effetto leggermento diverso ripetto a quello che ci si potrebbe aspettare. Quando si fa il casting di una variabile come stringa, per esempio, le variabili NULL e con valore booleano FALSE diventano stringhe vuote, 0 (o altri numeri) diventano stringhe di numeri, ed il valore booleano TRUE diventa "1:
Debugging del Codice
Non può essere lanciato nessun codice di debug al posto dell'add-ons, a meno che a questo non sia stato tolto il commento., per esempio var_dump(), print_r(), die(), and exit() sono chiamati in fase di creazione dell'add-on, se questi sono stati privati del commento.
Spazi Bianchi nei Files
Nessuno spazio bianco può precedere i tag di apertura di PHP o seguire quello di chiusura. L'output è bafferizzato, e gli spazi bianchi nei file possono causare un output prima che CodeIgniter inizi a trasmettere il proprio output, il che porta ad errori ed all'incapacità da parte di CodeIgniter di inviare un header pulito. Nell'esempio sotto, seleziona il testo con il mouse per vedere gli spazi bianchi sbagliati.
Compatibilità
A meno che non sia specificatamente menzionato nella documentazione add-on, tutto il codice deve essere compatibile con la versione di PHP 4.3+. InoltreUnless specifically mentioned in your add-on's documentation, all code must be compatible with PHP version 4.3+. Additionally, do not use PHP functions that require non-default libraries to be installed unless your code contains an alternative method when the function is not available, or you implicitly document that your add-on requires said PHP libraries.
Class and File Names using Common Words
When your class or filename is a common word, or might quite likely be identically named in another PHP script, provide a unique prefix to help prevent collision. Always realize that your end users may be running other add-ons or third party PHP scripts. Choose a prefix that is unique to your identity as a developer or company.
INCORRECT: class Email pi.email.php class Xml ext.xml.php class Import mod.import.php CORRECT: class Pre_email pi.pre_email.php class Pre_xml ext.pre_xml.php class Pre_import mod.pre_import.php
Nomi delle Tabelle del Database
Per ogni tabella che viene aggiunta sarebbe necessario aggiugere il prefisso 'exp_', seguito da un prefisso unico che identifica la propria azienda o se stessi come sviluppatori, e successivamente un breve nome descrittivo della tabella. Non è necessario preoccuparsi del prefisso del database utilizzato nella propria installazione, la classe database di CodeIgniter convertirà automaticamente 'exp_' in quello che viene attualmente utilizzato.
NOTE: Ricorda che MySQL ha un limite di 64 caratteri per i nomi delle tabelle.has a limit of 64 characters for table names. Questo non dovrebbe essere un problema in quanto tabelle con nomi che superano questo limite sono irragionevoli. Per esempio, This should not be an issue as table names that would exceed this would likely have unreasonable names. For instance, the following table name exceeds this limitation by one character. Silly, no? exp_pre_email_addresses_of_registered_users_in_seattle_washington
Una Classe per File
Utilizza un file per ogni classe che viene creata, a meno che le classi non siano strettamente collegate. Un esempio in CodeIgnier dove un file contiene più classi è la Classe Database, che contiene la classe DB e la classe DB_Cashe, e il plugin Magpie, che contiene sia la classe Magpie che Snoopy.
Whitespace
Non utilizzare gli spazi nel proprio codice, ma i tabs.Use tabs for whitespace in your code, not spaces. Questo può sembrare una piccola cosa, ma usando i tabs invece degli spazi bianchi, lo sviluppatore ha la possibilità di vedere il proprio codice indentato a prescindere all'applicazione che viene utilizzata. Inoltre rende il file più compatto, infatti un carattere tab equivale a 4 caratteri spazio.
Interruzione di Linea
I files devono essere salvati con l'interruzione di linea Unix. Questoè più di un problema per un programmatore che lavora in ambiente Windows, ma in ogni caso assicurarsi che il prorio editor di testo sia configurato con l'interruzione di linea Unix.
Indentare il Codice
Usate lo stile di indentazione Allman. Ad eccezione della dichiarazione della Classe, le parentesi sono poste sempre su linee da sole, With the exception of Class declarations, braces are always placed on a line by themselves, e rientrato allo stess livello del comando alle quali appartengono.
Spazio e Parentesi
In generale, alle parentesi non si aggiungono spazzi aggiuntivi.In general, parenthesis and brackets should not use any additional spaces. L'unica eccezione sta nello spazio che deve seguire le strutture di controllo in PHP le quali accettano argomenti con parentesi (dichiarare , do-while, elseif, for, foreach, if, switch, while), perché aiutano a distinguerle dalle funzioni e ne migliora la lettura.
Localizzare il Testo nel Pannello di Controllo
Qualsiasi testo che va in output nel pannello di controllo dovrebbe usare le variabili di linguaggio del file del modulo lang per permetterne la localizzazione.
Metodi e Variabili Privati
Metodi e variabili che sono accessibili solo all'inteno della propria classe, come fuzioni di utility o helper che i metodi pubblici utilizzano per astrazione del codice, dovrebbero avere un underscore come prefisso.
Errori PHP
Il cdice deve essere libero da errori, e non deve nascondere warning o comunicazioni. Per esempio, non accedere mai ad una variabile che non si è settata personalmente (come l'array $_POST) senza prima fare un controllo con la funzione isset().
Assicurarsi che, quando si sta sviluppando il proprio add-on, il report degli errori sia disponibile per TUTTI gli utenti, e che l'opzione display_errors sia abilitata nell'ambiente PHP nel quale si sta lavorando. Questo è possibile verificarlo con il seguente comando:
Su alcuni server dove display_erorrs è disabilitato, e dove non si ha la possibilità di cambiare il file php.ini, è possibile abilitarlo nel seguente modo:
NOTA: Impostando il display_errors attraverso il comando ini_set() durante l'esecuzione non sia ha la stessa situazione di quando questo è abilitato a livello di ambiente. Infatti, non avrà alcun effetto se lo script contiene errori fatali.
Abbreviaizone dei Tag di Apertura
Utilizzate sempre i tag PHP di apertura completi, nel caso il server sul quale lavorate non abbia lo short_open_tag abilitato.
Un comando per linea
Non inserire in una unica linea più comandi.
Stringhe
Utilizzare sempre stringe tra apici, a meno che non si voglia passare una variabile, e nel caso lo si volgia fare, utilizzate le parentesi graffe. E' possibile utilizzare doppie virgolette qual'ora la stringa contenga testo con apici, questo per evitare di utilizzare i caratteri di escape.
Queries SQL
Le parole chiave MySQL devono essere scritte sempre maiuscole: SELECT, INSERT, UPDATE, WHERE, AS, JOIN, ON, IN, etc.
Spezzate lunghe queries in puù linee per favorire la leggibilità, preferibilmente ad ogni clausola.
Argomenti di Default delle Funzioni
Quando opportuno, è buona norma prevedere un parametro di default per le funzioni, al fine di aiutare a prevenire errori PHP nati da chiamate sbagliate. Per esempio:
Sovrapposizione dei Parametri dei Tag
Evitare i parametri multipli che hanno effetto sulla stessa cosa. Per esempio, invece di include= e exclude=, forse utilizzare solo include= come unico parametro, con l'aggiunta di un "not", per esempio include="not bar". Questo permetterà di prevenire sovrapposizione di parametri o preoccuparsi di quale parametro ha la priorità rispetto ad un altro.
Ultimo aggiornamento ( Lunedì 29 Novembre 2010 04:38 )