phpBB

Development Wiki

Italiano:Coding guidelines

From phpBB Development Wiki

This article is a stub. You can help in improving Olympus Documentation by expanding it.

phpBB3 New Coding Guidelines

Impostazioni Predefinite

Impostazioni per gli editor di testo

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 File

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 
*
*/

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

<!-- IF S_KEYWORD_VERSION -->
<!--
/**
*
* @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 
*
*/
//-->
<!-- ENDIF -->

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}
*/

/**
* @ignore
*/
Small code snippedmostly one or two defines or an if statement

/**
* {DOCUMENTATION}
*/
class ...

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
/includes/acm, /includes/cache.php
  • acp - Administration Control Panel
/adm, /includes/acp, /includes/functions_admin.php
  • dbal - Database Abstraction Layer.
/includes/db

Base class is dbal

  • Base DBAL class, defining the overall framework as well as common denominators
/includes/db/dbal.php
  • Firebird/Interbase Database Abstraction Layer
/includes/db/firebird.php
  • MSSQL Database Abstraction Layer
/includes/db/msssql.php
  • MSSQL ODBC Database Abstraction Layer for MSSQL
/includes/db/mssql_odbc.php
  • MySQL Database Abstraction Layer for MySQL 3.x/4.0.x
/includes/db/mysql.php
  • MySQL4 Database Abstraction Layer for MySQL 4.1.x/5.x
/includes/db/mysql4.php
  • MySQLi Database Abstraction Layer
/includes/db/mysqli.php
  • Oracle Database Abstraction Layer
/includes/db/oracle.php
  • PostgreSQL Database Abstraction Layer
/includes/db/postgres.php
  • Sqlite Database Abstraction Layer
/includes/db/sqlite.php
  • docs - phpBB3 Documentation
/docs
  • images - All global images not connected to styles
/images
  • install - Installation System
/install
  • language - All language files
/language
  • login - Login Authentication Plugins
/includes/auth
  • VC - (Visual Confirmation / CAPTCHA)
/includes/captcha
  • mcp - Moderator Control Panel
/mcp.php, /includes/mcp, report.php
  • ucp - User Control Panel
/ucp.php, /includes/ucp
  • search - Search System
/includes/search, search.php
  • styles - phpBB Styles/Templates/Themes/Imagesets
/styles, style.php

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 $g_iPersonAge or $grLogData 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 $i as the variable for the outer loop.
When there is a loop inside that loop, it's index should be $j, followed by $k, 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; print_login_status_for_a_given_user() goes too far, for example -- that function would be better named print_user_login_status(), or just print_login_status().
It should be possible to tell the main purpose of a function just by looking at the first line, e.g. get_user_data($username). 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: do_stuff($a, $b, $c). 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.

Code Layout

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 (conditiondo_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() 
{
    ...
}

See Also

Text Editors
Best Practices

External Links

phpBB3 Coding Guidelines