diff --git a/phpBB/docs/coding-guidelines.html b/phpBB/docs/coding-guidelines.html index ee0b9f4e86..d45a39f4df 100644 --- a/phpBB/docs/coding-guidelines.html +++ b/phpBB/docs/coding-guidelines.html @@ -179,7 +179,7 @@ body {
-

This is the April, 2005 revision of the phpBB Coding Guidelines, all attempts should be made to follow it as closely as possible. This document is (c) 2005 phpBB Group, copying or redistribution is not allowed without permission.

+

These are the phpBB Coding Guidelines for Olympus, all attempts should be made to follow it as closely as possible. This document is (c) 2006 phpBB Group, copying or redistribution is not allowed without permission.

Coding Guidelines

@@ -200,6 +200,7 @@ body {
  • Styling
  • Templating
    • +
  • Guidelines Changelog
    • @@ -212,6 +213,14 @@ body {

    Tabs vs Spaces:

    In order to make this as simple as possible, we will be using tabs, not spaces. Feel free to set how many spaces your editor uses when it displays tabs, but make sure that when you save the file, it's saving tabs and not spaces. This way, we can each have the code be displayed the way we like it, without breaking the layout of the actual files.

    +

    Additionally please check your editor for the indent size. If tabs are set to 4 spaces for example, the indent size needs to be 4 too:

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

    If entered with tabs (replace the {TAB}) both equal signs need to be on the same column.

    Linefeeds:

    Ensure that your editor is saving files in the UNIX format. This means lines are terminated with a newline, not with a CR/LF combo as they are on Win32, or whatever the Mac uses. Any decent editor should be able to do this, but it might not always be the default. Know your editor. If you want advice on Windows text editors, just ask one of the developers. Some of them do their editing on Win32.

    @@ -233,7 +242,7 @@ body { * * @package {PACKAGENAME} * @version $Id: $ -* @copyright (c) 2005 phpBB Group +* @copyright (c) 2006 phpBB Group * @license http://opensource.org/licenses/gpl-license.php GNU Public License * */ @@ -247,9 +256,7 @@ body { 
     /**
-*
 * {HEADER}
-*
 */
 
 /**
@@ -303,28 +310,34 @@ class ...
 		
  • phpBB3
    Core files and all files not assigned to a seperate package
    • 
 		
  • acm
    /includes/acm
    Cache System, seperated because of equal class names
 			
      
+				
    • acm_main
      /includes/acm/acm_main.php
      Base caching class. All functions obtaining cached data should be placed into this file
      • 
 				
    • acm_db
      /includes/acm/acm_db.php
      Database based caching
      • 
 				
    • acm_file
      /includes/acm/acm_file.php
      File based caching
      • 
 			
    
 		
    • 
-		
  • dbal
    /includes/db
    Database Abstraction Layer, seperated because of equal class names.
    Every database class is a seperate package preceeded by dbal_
+		
  • acp
    /adm, /includes/acp, /includes/functions_admin.php
    Administration Control Panel
    • 
+		
  • dbal
    /includes/db
    Database Abstraction Layer.
    Base class is dbal
 			
      
-				
    • dbal_db2
      /includes/db/db2.php
      DB2 Database Abstraction Layer
      • 
 				
    • dbal_firebird
      /includes/db/firebird.php
      Firebird/Interbase Database Abstraction Layer
      Minimum Requirement is Firebird 1.5+/Interbase 7.1+
      • 
 				
    • dbal_mssql
      /includes/db/msssql.php
      MSSQL Database Abstraction Layer
      Minimum Requirement is MSSQL 2000+
      • 
-				
    • dbal_odbc_mssql
      /includes/db/mssql-odbc.php
      MSSQL ODBC Database Abstraction Layer for MSSQL
      Minimum Requirement is Version 2000+
      • 
+				
    • dbal_mssql_odbc
      /includes/db/mssql_odbc.php
      MSSQL ODBC Database Abstraction Layer for MSSQL
      Minimum Requirement is Version 2000+
      • 
 				
    • dbal_mysql
      /includes/db/mysql.php
      MySQL Database Abstraction Layer
      Minimum Requirement is 3.23+/4.0+/4.1+
      • 
-				
    • dbal_mysqli
      /includes/db/mysqli.php
      MySQL4 Database Abstraction Layer
      Minimum Requirement is MySQL 4.1+
      • 
+				
    • dbal_mysql4
      /includes/db/mysql4.php
      MySQL4 Database Abstraction Layer
      Minimum Requirement is 4.0+/4.1+/5.0+
      • 
+				
    • dbal_mysqli
      /includes/db/mysqli.php
      MySQLi Database Abstraction Layer
      Minimum Requirement is MySQLi extension with MySQL 4.1+/5.0+
      • 
 				
    • dbal_oracle
      /includes/db/oracle.php
      Oracle Database Abstraction Layer
      • 
 				
    • dbal_postgres
      /includes/db/postgres.php
      PostgreSQL Database Abstraction Layer
      Minimum Requirement is Version 7.3+
      • 
 				
    • dbal_sqlite
      /includes/db/sqlite.php
      Sqlite Database Abstraction Layer
      • 
 			
    
 		
    • 
+		
  • docs
    /docs
    phpBB Documentation
    • 
+		
  • images
    /images
    All global images not connected to styles
    • 
+		
  • install
    /install
    Installation System
    • 
+		
  • language
    /language
    All language files
    • 
 		
  • login
    /includes/auth
    Login Authentication Plugins
    • 
-		
  • mcp
    mcp.php, /includes/mcp
    Moderator Control Panel
    • 
+		
  • mcp
    mcp.php, /includes/mcp, report.php
    Moderator Control Panel
    • 
 		
  • ucp
    ucp.php, /includes/ucp
    User Control Panel
    • 
-		
  • search
    /includes/search
    Search System
    • 
-		
  • acp
    /adm
    Administration Control Panel
    • 
+		
  • search
    /includes/search, search.php
    Search System
    • 
+		
  • styles
    /styles, style.php
    phpBB Styles/Templates/Themes/Imagesets
    •
    @@ -335,6 +348,8 @@ class ...

    2. Code Layout/Guidelines

    +

    Please note that these Guidelines also applies to js code.

    + 2.i. Variable/Function Naming

    @@ -468,7 +483,7 @@ do_stuff( $i, "foo", $b ); do_stuff($i, "foo", $b); for($i=0; $i<$size; $i++) ... -for($i = 0; $i < $size; $i++) ... +for ($i = 0; $i < $size; $i++) ... $i=($j < $size)?0:1; $i = ($j < $size) ? 0 : 1; @@ -484,12 +499,12 @@ $bool = ($i < 7 && $j > 8 || $k == 4);

    // now you can be certain what I'm doing here.

    -$bool = (($i < 7) && (($j < 8) || ($k == 4)))
+$bool = (($i < 7) && (($j < 8) || ($k == 4)));

    // But this one is even better, because it is easier on the eye but the intention is preserved

    -$bool = ($i < 7 && ($j < 8 || $k == 4))
+$bool = ($i < 7 && ($j < 8 || $k == 4));

    Quoting strings:

    @@ -590,6 +605,92 @@ if (isset($forum)) ... if (isset($forum) && $forum == 5) +

    Switch statements:

    +

    Switch/case code blocks can get a bit long sometimes. To have some level of notice and being in-line with the opening/closing brace requirement (where they are on the same line for better readability), this also applies to switch/case code blocks and the breaks. An example:

    + +

    // Wrong

    + 
    +switch ($mode)
+{
+	case 'mode1':
+		// I am doing something here
+		break;
+	case 'mode2':
+		// I am doing something completely different here
+		break;
+}
+
    + +

    // Good

    + 
    +switch ($mode)
+{
+	case 'mode1':
+		// I am doing something here
+	break;
+
+	case 'mode2':
+		// I am doing something completely different here
+	break;
+
+	default:
+		// Always assume that the case got not catched
+	break;
+}
+
    + +

    // Also good, if you have more code between the case and the break

    + 
    +switch ($mode)
+{
+	case 'mode1':
+
+		// I am doing something here
+
+	break;
+	
+	case 'mode2':
+	
+		// I am doing something completely different here
+
+	break;
+
+	default:
+
+		// Always assume that the case got not catched
+
+	break;
+}
+
    + +

    Even if the break for the default case is not needed, it is sometimes better to include it just for readability and completeness.

    + +

    If no break is intended, please add a comment instead. An example:

    + +

    // Example with no break

    + 
    +switch ($mode)
+{
+	case 'mode1':
+	
+		// I am doing something here
+
+	// no break here
+
+	case 'mode2':
+
+		// I am doing something completely different here
+
+	break;
+
+	default:
+
+		// Always assume that the case got not catched
+
+	break;
+}
+
    +
    Top

    @@ -604,7 +705,7 @@ if (isset($forum) && $forum == 5)

    All SQL commands should utilise the DataBase Abstraction Layer (DBAL)

    SQL code layout:

    -

    SQL Statements are often unreadable without some formatting, since they tend to be big at times. Though the formatting of sql statements adds a lot to the readability of code. SQL statements should be formatted in the following way, basically writing keywords :

    +

    SQL Statements are often unreadable without some formatting, since they tend to be big at times. Though the formatting of sql statements adds a lot to the readability of code. SQL statements should be formatted in the following way, basically writing keywords: 

     $sql = 'SELECT * 
@@ -648,7 +749,7 @@ $sql = 'SELECT *
 
 	
    Common DBAL methods: 
    
 
-	
    Always use $db->sql_escape() if you need to check for a string within an SQL statement, for example:
    
+	
    Always use $db->sql_escape() if you need to check for a string within an SQL statement (even if you are sure the variable can not contain single quotes - never trust your input), for example:
    
 
 	
     $sql = 'SELECT *
@@ -683,6 +784,8 @@ $sql = 'UPDATE ' . SOME_TABLE . '
 $db->sql_query($sql);
 	
    
 
+	
    The $db->sql_build_array() function supports the following modes: INSERT (example above), INSERT_SELECT (building query for INSERT INTO table (...) SELECT value, column ... statements), MULTI_INSERT (for returning extended inserts), UPDATE (example above) and SELECT (for building WHERE statement [AND logic]).
    
+
 	
 	Top
 	

    
@@ -729,7 +832,8 @@ for ($i = 0, $size = sizeof($post_data); $i < $size; $i++)
 	
    No attempt should be made to remove any copyright information (either contained within the source or displayed interactively when the source is run/compiled), neither should the copyright information be altered in any way (it may be added to)
    
 
 	
    Variables: 
    
-	
    Make use of the request_var() function for anything except for submit or single checking params. Example:
    
+	
    Make use of the request_var() function for anything except for submit or single checking params. 
    
+	
    The request_var function determines the type to set from the second parameter (which determines the default value too). If you need to get a scalar variable type, you need to tell this the request_var function explicitly. Examples:
    
 
 	
    // Old method, do not use it
    
 	
    @@ -748,10 +852,20 @@ $submit = (isset($_POST['submit'])) ? true : false;
 $start = request_var('start', '0');
 	
    
 
+	
    // Getting an array, keys are integers, value defaults to 0
+	
    +$mark_array = request_var('mark', array(0));
+
    + +

    // Getting an array, keys are strings, value defaults to 0 + 

    +$action_ary = request_var('action', array('' => 0));
+
    +

    Login checks/redirection:

    To show a forum login box use login_forum_box($forum_data), else use the login_box() function.

    -

    Sensitive Operatiosn:

    +

    Sensitive Operations:

    For sensitive operations always let the user confirm the action. For the confirmation screens, make use of the confirm_box() function.

    Sessions:

    @@ -772,8 +886,12 @@ $user->setup(); trigger_error('NO_FORUM');
    +

    Url formatting

    + +

    All urls pointing to internal files need to be prepended by the $phpbb_root_path variable. Within the administration control panel all urls pointing to internal files need to be prepended by the $phpbb_admin_path variable. This makes sure the path is always correct and users being able to just rename the admin folder and the acp still working as intended.

    +

    General Functions:

    -

    Use sizeof instead of count, this is just a general preference and guideline and has no other benefit.

    +

    Use sizeof instead of count, this is just a general preference and guideline and has no other benefit than to be consistent.

    Use strpos instead of strstr.

    @@ -1031,8 +1149,44 @@ markup Top +

    + +

    5. Guidelines Changelog

    +
    + +

    Revision 1.7

    + + + +

    Revision 1.6

    + + + +

    Revision 1.5

    + + + +

    Revision 1.3

    + + + +
    +Top +