Login
Libri
Home Argomenti Generali Stile e Sintassi

Stile e Sintassi

Share

La pagina seguente descrive le regole per scrivere codice quando si sviluppa CodeIgniter.

Tabella dei Contenuti

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
  1. Aprire Application Preferences
  2. Selezionare Advanced, e successivamente il tab "Saving"
  3. In "File Encoding", selezionare "UTF-8 (recommended)"
  4. In "Line Endings", selezionare "LF (recommended)"
  5. Opzionale: Seleziona "Use for existing files as well" se si desidera modificare le terminazioni di linea aperti con le nuove preferenze.
BBEdit
  1. Aprire Application Preferences
  2. Selezionare "Text Encodings" sulla sinistra.
  3. In "Default text encoding for new documents", selezionare "Unicode (UTF-8, no BOM)"
  4. Opzionale: In "If file's encoding can't be guessed, use", si scelga "Unicode (UTF-8, no BOM)"
  5. Selezionare"Text Files" sulla sinistra.
  6. 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.


INCORRECT:

<?php echo "Here's my code!"; ?>

CORRECT:

<?php echo "Here's my code!";

/* End of file myfile.php */
/* Location: ./system/modules/mymodule/myfile.php */ 

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.


INCORRECT:

class superclass
class SuperClass

CORRECT:

class Super_class

Si noti che il nome della Classe e del suo costruttore devo essere identici:


class Super_class {

 function Super_class() {

 }
}

Esempi di nomi corretti e incorretti:


INCORRECT:

function fileproperties()
// not descriptive and needs underscore separator

function fileProperties()
// not descriptive and uses CamelCase

function getfileproperties()
// Better! But still missing underscore separator

function getFileProperties()
// uses CamelCase

function get_the_file_properties_from_the_file()
// verboso


CORRECT:

function get_file_properties()
// descriptive, underscore separator, and all lowercase letters

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().


INCORRECT:

$j = 'foo';
// single letter variables should only be used in for() loops

$Str
// contains uppercase letters

$bufferedText
// uses CamelCasing, and could be shortened without losing semantic meaning

$groupid
// multiple words, needs underscore separator

$name_of_last_city_used

// too long


CORRECT:

for ($j = 0; $j < 10; $j++)

$str

$buffer

$group_id $last_city 

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:


/**
* Super Class
*
* @package Package Name
* @subpackage Subpackage
* @category Category
* @author Author Name
* @link http://example.com */
class Super_class {


/**
* Encodes string for use in XML
*
* @access public
* @param string
* @return string
*/
function xml_encode($str)

Utilizza il commento a linea singola all'interno del codice lasciando una linea biancha tra i blocchi di commenti lunghi e il codice.


// break up the string by newlines
$parts = explode("\n", $str);

// A longer comment that needs to give greater detail on what is
// occurring and why can use multiple single-line comments. Try to
// keep the width reasonable, around 70 characters is the easiest to
// read. Don't hesitate to link to permanent external resources
// that may provide greater detail:
//
// http://example.com/information_about_something/in_particular/

$parts = $this->foo($parts); 

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.


INCORRECT:

myConstant
// missing underscore separator and not fully uppercase

N
// no single-letter constants

S_C_VER
// not descriptive

$str = str_replace('{foo}', 'bar', $str);
// should use LD and RD constants

CORRECT:

MY_CONSTANT

NEWLINE

SUPER_CLASS_VERSION

$str = str_replace(LD.'foo'.RD, 'bar', $str); 

TRUE, FALSE, and NULL

Le parole chiave TRUE, FALSE, e NULL dovrebbero essere sempre scritte in maiuscolo.


INCORRECT:

if ($foo == true) $bar = false;

function foo($bar = null)

CORRECT:

if ($foo == TRUE) $bar = FALSE;

function foo($bar = NULL)

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.


INCORRECT:

if ($foo || $bar)

if ($foo AND $bar)
// okay but not recommended for common syntax highlighting applications

if (!$foo)

if (! is_array($foo))

CORRECT:

if ($foo OR $bar)

if ($foo && $bar)
// recommended

if ( ! $foo) if ( ! is_array($foo)) 

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.


INCORRECT:

// If 'foo' is at the beginning of the string, strpos will return a 0,
// resulting in this conditional evaluating as TRUE
if (strpos($str, 'foo') == FALSE)

CORRECT:

if (strpos($str, 'foo') === FALSE)


INCORRECT:

function build_string($str = "") { if ($str == "")
// uh-oh! What if FALSE or the integer 0 is passed as an argument? { } }

CORRECT:

function build_string($str = "") { if ($str === "") { } }

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:


$str = (string) $str; // cast $str as a string

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.


// print_r($foo);

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.


INCORRECT:

<?php
 // ...there is whitespace and a linebreak above the opening PHP tag
 // as well as whitespace after the closing PHP tag
?>

CORRECT:

<?php
 // this sample has no whitespace before or after the opening and closing PHP tags
?>

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.


INCORRECT:

email_addresses
// missing both prefixes

pre_email_addresses
// missing exp_ prefix

exp_email_addresses
// missing unique prefix

CORRECT:

exp_pre_email_addresses 

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.


INCORRECT:

function foo($bar) {
 //...
}

foreach ($arr as $key => $val) {
 // ...
}

if ($foo == $bar) {
 // ...
} else {
 // ...
}

for ($i = 0; $i < 10; $i++)
 {
 for ($j = 0; $j < 10; $j++)
 {
 // ...
 }
 }
 
CORRECT:

function foo($bar)
{
 // ...
}

foreach ($arr as $key => $val)
{
 // ...
}

if ($foo == $bar)
{
 // ...
}
else
{
 // ...
}

for ($i = 0; $i < 10; $i++)
{
 for ($j = 0; $j < 10; $j++)
 {
 // ...
 }
}

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.


INCORRECT:

$arr[ $foo ] = 'foo';

CORRECT:

$arr[$foo] = 'foo';
// no spaces around array keys

INCORRECT:

function foo ( $bar )
{

}

CORRECT:

function foo($bar)
{
}
// no spaces around parenthesis in function declarations

INCORRECT:

foreach( $query->result() as $row )

CORRECT:

foreach ($query->result() as $row)
// single space following PHP control structures, but not in interior parenthesis

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.


INCORRECT:

return "Invalid Selection";

CORRECT:

return $LANG->line('invalid_selection');

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.


convert_text()
// public method

_convert_text()
// private method

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:


if (ini_get('display_errors') == 1) { exit "Enabled"; }

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:


ini_set('display_errors', 1);

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.


INCORRECT:

<? echo $foo; ?>

<?=$foo?>


CORRECT:

<?php echo $foo; ?>

Un comando per linea

Non inserire in una unica linea più comandi.


INCORRECT:

$foo = 'this'; $bar = 'that'; $bat = str_replace($foo, $bar, $bag);

CORRECT:

$foo = 'this';
$bar = 'that';
$bat = str_replace($foo, $bar, $bag); 

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.


INCORRECT:

"My String"
// no variable parsing, so no use for double quotes

"My string $foo"
// needs braces

'SELECT foo FROM bar WHERE baz = \'bag\''
// ugly

CORRECT:

'My String'

"My string {$foo}"

"SELECT foo FROM bar WHERE baz = 'bag'"

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.


INCORRECT:

// keywords are lowercase and query is too long for
// a single line (... indicates continuation of line)
$query = $this->db->query("select foo, bar, baz, foofoo, foobar as raboof, foobaz from exp_pre_email_addresses
...where foo != 'oof' and baz != 'zab' order by foobaz limit 5, 100");

CORRECT: $query = $this->db->query("SELECT foo, bar, baz, foofoo, foobar AS raboof, foobaz
 FROM exp_pre_email_addresses
 WHERE foo != 'oof'
 AND baz != 'zab'
 ORDER BY foobaz
 LIMIT 5, 100");


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:


function foo($bar = '', $baz = FALSE)

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 )