Italiano:Coding guidelines

Coding guidelines Coding guidelines Coding guidelines phpBB3 New Coding Guidelines

TABs contro Spazi
Allo scopo di conservare una consistenza nel layout del codice dei files, phpBB3 usa un TAB di 4 spazi anzichè gli spazi stessi. La maggior parte degli Editor di testo offre l'opzione adatta a settare la larghezza dei TAB, nelle Preferenze.

I TAB davanti alle linee non sono un problema ma potrebbe invece esserlo averli nel testo se non settiamo appunto il TAB allo stesso numero di spazi che noi tutti usiamo (appunto 4 spazi). Qui c'è un piccolo esempio di come dovrebbe essere:

{TAB}$mode{TAB}{TAB}= request_var('mode', ''); {TAB}$search_id{TAB}= request_var('search_id', '');

Se inserito con i TABs (sostituisci il {TAB}) entrambi i segni di uguale(=) devono essere sulla stessa colonna.

Formato del Fine Linea
Assicurati che il tuo Editor stia salvando i files nel formato di fine linea LF UNIX/Mac OS X. Questo significa che le linee terminano con una nuova linea e non con una combinazione di CR/LF (Carriage Return/Line Feed) poichè essa appartiene ai sistemi Win32 od al formato classico CR Mac. La maggior parte dei Text Editors hanno la possibilità di settare il formato di fine linea.

Encoding
Grazie al supporto UTF-8 è possibile salvare tutti i file di lingua con una codifica file in UTF-8. E' importante controllare le preferenze del vostro editor di testo per garantire che i file vengono salvati in formato UTF-8. Molti editor di testo non salvano i file in formato UTF-8 per impostazione predefinita.

Intestazione standard per i nuovi file
Questo modello di intestazione deve essere inclusa nella parte superiore di tutti i file di phpBB: /**
 * @author Original Author author@example.com
 * @author Another Author another@example.com
 * @package {PACKAGENAME}
 * @version $Id:$
 * @copyright (c) 2007 Your Group Name
 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
 * @copyright (c) 2007 Your Group Name
 * @license http://opensource.org/licenses/gpl-license.php GNU Public License

To use the header in a template package, use the following code at the top of the template file:

See Package Names for the correct package name to use.

File contenenti codice inline
Per i file è necessario inserire un commento vuoto direttamente dopo l'intestazione per impedire l'assegnazione del documento con l'elemento del primo codice trovato.

/**
 * {HEADER}

/** {CODE}

File che contengono solo le funzioni
Non dimenticate di commentare le funzioni (soprattutto la prima funzione che segue l'intestazione). Ogni funzione deve contenere almeno un commento di ciò che questa funzione fa. Per le funzioni più complesse si consiglia di documentare i parametri in più con il tag

File contenenti solo le classi
Non dimenticate di commentare le classi, ogni classe necessita di un pacchetto separato @ definizione, è lo stesso del nome del pacchetto di intestazione. Oltre a questo caso particolare di dichiarazione di cui sopra per i file contenenti funzioni deve essere applicato alle classi e ai suoi metodi. Codice per le funzioni di intestazione, ma solo / classi di file:

Se questo caso è vero, il metodo migliore per evitare confusione nella documentazione è l'aggiunta di un comando di ignorare, ad esempio:

/**
 * {HEADER}

/** Small code snipped, mostly one or two defines or an if statement
 * @ignore

/** class ...
 * {DOCUMENTATION}

Locazione file
Le funzioni utilizzate da più di una pagina deve essere collocata in functions.php, o nelle funzioni dei relativi file collocate in / includes /. Le funzioni specifiche di una pagina devono essere collocate nella stessa o nelle sezioni di file con proprie funzioni. Alcuni file in / includes assumono le funzioni responsabili di sezioni speciali, ad esempio per i file di esempio il caricamento, per la visualizzazione di "cose​​", funzioni utente collegato e così via. I seguenti pacchetti sono stati definiti, e relative nuove caratteristiche / funzioni deve essere collocato all'interno del file di cui / posizioni, così come specifica il corretto Package Names. I nomi dei pacchetti sono evidenziate in grassetto all'interno di questo elenco:


 * phpBB3 - Core files and all files not assigned to a separate package


 * acm - Cache System


 * acp - Administration Control Panel


 * dbal - Database Abstraction Layer.

Base class is dbal
 * Base DBAL class, defining the overall framework as well as common denominators
 * Firebird/Interbase Database Abstraction Layer
 * MSSQL Database Abstraction Layer
 * MSSQL ODBC Database Abstraction Layer for MSSQL
 * MySQL Database Abstraction Layer for MySQL 3.x/4.0.x
 * MySQL4 Database Abstraction Layer for MySQL 4.1.x/5.x
 * MySQLi Database Abstraction Layer
 * Oracle Database Abstraction Layer
 * PostgreSQL Database Abstraction Layer
 * Sqlite Database Abstraction Layer
 * MySQL4 Database Abstraction Layer for MySQL 4.1.x/5.x
 * MySQLi Database Abstraction Layer
 * Oracle Database Abstraction Layer
 * PostgreSQL Database Abstraction Layer
 * Sqlite Database Abstraction Layer
 * PostgreSQL Database Abstraction Layer
 * Sqlite Database Abstraction Layer
 * Sqlite Database Abstraction Layer
 * Sqlite Database Abstraction Layer


 * docs - phpBB3 Documentation


 * images - All global images not connected to styles


 * install - Installation System


 * language - All language files


 * login - Login Authentication Plugins


 * VC - (Visual Confirmation / CAPTCHA)


 * mcp - Moderator Control Panel


 * ucp - User Control Panel


 * search - Search System


 * styles - phpBB Styles/Templates/Themes/Imagesets

Code Layout Guidelines
These Guidelines apply to all php, html, javascript and css files.

Variable/Function Naming
phpBB3 does not use hungarian notation in any naming conventions. Many guidelines use hungarian notation, which is basically prepending prefixes to variables, such as "g_" or "g" to global, "i_" or "i" to integer data types, etc... However, hungarian is not relevant to PHP, it also produces variable names such as  or   which is not easily readable at a glance and usually ends up causing some naming confusion.

Variable Names
phpBB3 variables names should consist of all lowercase, with words separated by underscores.

 Incorrect Method  $currentuser $variablename $extendedvariablename

$Current_User $Variable_Name $Extended_Variable_Name

$CurrentUser $VariableName $ExtendedVariableName

 Correct Method  $current_user $variable_name $extended_variable_name

Variable names should be descriptive, but also concise. Whenever possible, keep variable names to under 18 characters. But it's better to have a longer variable name than sacrafice clarity.

 Incorrect Method  $current_date_and_time $private_messages_text_unread

 Correct Method  $now $privmsgs_text_unread

Loop Indices
Loops are the only occassion where a short variable name (such as a single character) are permitted, and encouraged is when it's the index for a looping construct. Unless you already have a specific counting variable, use  as the variable for the outer loop. When there is a loop inside that loop, it's index should be, followed by  , and so on.

Example: for ($i = 0; $i < $outer_size; $i++) {	for ($j = 0; $j < $inner_size; $j++) {		for ($k = 0; $k < 3; $k++) {			foo($i, $j, $k); }	} }

Function Names
Function names should follow the same guidelines as variable names. Function names should contain a verb whenever possible.  Incorrect  a_function_which_gets_user_data_from_a_file stristr

 Correct  get_user_data print_login_status validate_form_data

The basic philosophy here is to not hurt code clarity for the sake of laziness. This has to be balanced by a little bit of common sense, though;  goes too far, for example -- that function would be better named , or just. It should be possible to tell the main purpose of a function just by looking at the first line, e.g. . By examination, you can make a good guess that this function gets the user data of a user with the username passed in the $username argument.

Function Arguments
Arguments are subject to the same guidelines as variable names. We don't want a bunch of functions like:. In most cases, we'd like to be able to tell how to use a function by just looking at its declaration. Function arguments should be separated by spaces, both when the function is defined and when it is called. However, there should not be any spaces between the arguments and the opening/closing brackets.

Examples: get_user_data( $username, $password, $variable ); // incorrect spaces next to brackets get_user_data($username,$password,$variable);	// incorrect no spaces between arguments get_user_data($a, $b, $c);		// incorrect, what do $a, $b, and $c hold? get_user_data($username, $password, $variable);	// correct

Special Namings
For all emoticons use the term smiley in singular and smilies in plural.

Always include the brackets
This is another case of lazy coding by dropping the brackets, causing problems with code clarity. Even if the body of a construct is only one code line in length, do not drop the brackets.

 Incorrect  if (condition) do_stuff;

if (condition) do_stuff;

while (condition) do_stuff;

for ($i = 0; $i < size; $i++) do_stuff($i);

 Correct  if (condition) {	do_stuff; }

while (condition) {	do_stuff; }

for ($i = 0; $i < size; $i++) {	do_stuff; }

Where to put the brackets
phpBB coding standards require that brackets go on their own line. The closing brackets should always be at the same column as the corresponding opening brackets.  Incorrect  if (condition) { while (condition2) { for ($i = 0; $i < $size; $i++) { ...}} } else { ... }

if (condition) { while (condition2) { for ($i = 0; $i < $size; $i++) { ...		}	} } else { ... }

 Correct  if (condition) {	while (condition2) {		for ($i = 0; $i < $size; $i++) {			...		}	} } else {	... } while (condition) {	... } function do_stuff {	... }