Coding guidelines
From phpBB Development Wiki
phpBB3 New Coding Guidelines
Contents |
Defaults
Editor Settings
Tabs vs Spaces
In order to maintain consistency within the code, phpBB3 uses 4 space tabs instead of spaces.
Most decent editors will have the ability to set tab width preferences.
The reason for this is to maintain the layout of the file to be consistent with the phpBB3 core.
Tabs in front of lines are no problem, but having them within the text can be a problem if you do not set it to the amount of spaces every one of us uses. Here is a short example of how it should look like:
{TAB}$mode{TAB}{TAB}= request_var('mode', '');
{TAB}$search_id{TAB}= request_var('search_id', '');
If entered with tabs (replace the {TAB}) both equal signs need to be on the same column.
Line Ending Format
Ensure that your editor is saving files in the LF UNIX/Mac OS X Line format. This means lines are terminated with a newline, not with a CR/LF combo as they are on Win32, or CR Mac Classic format. Most Text Editors have the ability to set line endings.
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 snipped, mostly 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 (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()
{
...
}
See Also
External Links
