phpBB

Development Wiki

Difference between revisions of "Italiano:Coding guidelines"

From phpBB Development Wiki

m
m (TABs contro Spazi)
Line 6: Line 6:
  
 
==== TABs contro Spazi ====
 
==== TABs contro Spazi ====
Allo scopo di conservare una consistenza nel codice, phpBB3 usa un TAB di 4 spazi anzichè gli spazi stessi.<br>
+
Allo scopo di conservare una consistenza nel layout del codice dei files, phpBB3 usa un TAB di 4 spazi anzichè gli spazi stessi.<br>
La maggior parte dei buoni Editor ha l'opzione adatta a settare la larghezza dei TAB nelle Preferenze.<br>
+
La maggior parte degli Editor di testo offre l'opzione adatta a settare la larghezza dei TAB, nelle Preferenze.<br>
La ragione di tutto questo è la necessità di conservare (l'abbiamo già detto sopra) il layout del file consistentemente col codice sorgente di phpBB3.<br>
+
  
 
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:<br>
 
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:<br>

Revision as of 23:10, 27 September 2008

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

phpBB3 New Coding Guidelines

Defaults

Settaggi 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

Due to support for UTF-8, it is important that you save all language files with a file encoding of UTF-8. Check preferences of you text editor to ensure files are saved as UTF-8. Many text editors don't save files as UTF-8 by default.

File Headers

Standard Header for new Files

This template of the header must be included at the top of all phpBB files:

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

Files containing inline code

For those files you have to put an empty comment directly after the header to prevent the documentor assigning the header to the first code element found.

/**
* {HEADER}
*/

/**
*/
{CODE}

Files containing only functions

Do not forget to comment the functions (especially the first function following the header). Each function should have at least a comment of what this function does. For more complex functions it is recommended to document the parameters too.

Files containing only classes

Do not forget to comment the class. Classes need a separate @package definition, it is the same as the header package name. Apart from this special case the above statement for files containing only functions needs to be applied to classes and its methods too.

Code following the header but only functions/classes file:

If this case is true, the best method to avoid documentation confusions is adding an ignore command, for example:

/**
* {HEADER}
*/

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

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

File Locations

Functions used by more than one page should be placed in functions.php, or in its own functions file located in /includes/. Functions specific to one page should be placed on that page (at the bottom) or within the relevant sections functions file. Some files in /includes are holding functions responsible for special sections, for example uploading files, displaying "things", user related functions and so forth.

The following packages are defined, and related new features/functions should be placed within the mentioned files/locations, as well as specifying the correct Package Names. The package names are bold within this list:

  • 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