From e29e0e5018ee0f783ad8d5b8a6a93fec1d5800b3 Mon Sep 17 00:00:00 2001 From: Cesar G Date: Tue, 27 May 2014 08:10:32 -0700 Subject: [ticket/12599] Remove corner images from documentation style. PHPBB3-12599 --- phpBB/docs/coding-guidelines.html | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) (limited to 'phpBB/docs/coding-guidelines.html') diff --git a/phpBB/docs/coding-guidelines.html b/phpBB/docs/coding-guidelines.html index 98cfe0e717..541d39ac2c 100644 --- a/phpBB/docs/coding-guidelines.html +++ b/phpBB/docs/coding-guidelines.html @@ -16,7 +16,7 @@
-
+
@@ -25,7 +25,7 @@

Skip

-
+
@@ -40,7 +40,7 @@

Coding Guidelines

-
+
@@ -89,7 +89,7 @@
-
+
@@ -97,7 +97,7 @@

1. Defaults

-
+
@@ -274,7 +274,7 @@ PHPBB_QA (Set board to QA-Mode, which means the updater also c
Back to Top
-
+
@@ -282,7 +282,7 @@ PHPBB_QA (Set board to QA-Mode, which means the updater also c

2. Code Layout/Guidelines

-
+
@@ -1169,14 +1169,14 @@ append_sid("{$phpbb_root_path}memberlist.$phpEx", 'mode=group&
Back to Top
-
+

3. Styling

-
+

3.i. Style Config Files

@@ -1252,14 +1252,14 @@ parent = prosilver
Back to Top
-
+

4. Templating

-
+

4.i. General Templating

@@ -1748,7 +1748,7 @@ This may span multiple lines.
Back to Top
-
+
@@ -1758,7 +1758,7 @@ This may span multiple lines.

5. Character Sets and Encodings

-
+
@@ -1821,7 +1821,7 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2))
Back to Top
-
+
@@ -1829,7 +1829,7 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2))

6. Translation (i18n/L10n) Guidelines

-
+
@@ -2538,7 +2538,7 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2))
Back to Top
-
+
@@ -2546,7 +2546,7 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2))

7. Copyright and disclaimer

-
+
@@ -2556,7 +2556,7 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2))
Back to Top
-
+
-- cgit v1.2.1 From 4565cac049be02e452de5707fdc692d624bdac8b Mon Sep 17 00:00:00 2001 From: Cesar G Date: Tue, 27 May 2014 08:12:06 -0700 Subject: [ticket/12599] Move documentation stylesheet to assets directory. PHPBB3-12599 --- phpBB/docs/coding-guidelines.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'phpBB/docs/coding-guidelines.html') diff --git a/phpBB/docs/coding-guidelines.html b/phpBB/docs/coding-guidelines.html index 541d39ac2c..18038a1c22 100644 --- a/phpBB/docs/coding-guidelines.html +++ b/phpBB/docs/coding-guidelines.html @@ -6,7 +6,7 @@ phpBB3 • Coding Guidelines - + -- cgit v1.2.1 From 14fecb2f028a618fc9856124a24ba3878406a658 Mon Sep 17 00:00:00 2001 From: Cesar G Date: Tue, 27 May 2014 08:37:17 -0700 Subject: [ticket/12599] Move images to assets/ and update the phpBB logo. PHPBB3-12599 --- phpBB/docs/coding-guidelines.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'phpBB/docs/coding-guidelines.html') diff --git a/phpBB/docs/coding-guidelines.html b/phpBB/docs/coding-guidelines.html index 18038a1c22..8e7da53025 100644 --- a/phpBB/docs/coding-guidelines.html +++ b/phpBB/docs/coding-guidelines.html @@ -19,7 +19,7 @@
- +

Coding Guidelines

Ascraeus coding guidelines document

Skip

-- cgit v1.2.1 From a07b29c1df8519e31401ec3d5f472c8a8f04431c Mon Sep 17 00:00:00 2001 From: Cesar G Date: Tue, 27 May 2014 09:26:49 -0700 Subject: [ticket/12599] Place standalone text in a box. PHPBB3-12599 --- phpBB/docs/coding-guidelines.html | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'phpBB/docs/coding-guidelines.html') diff --git a/phpBB/docs/coding-guidelines.html b/phpBB/docs/coding-guidelines.html index 8e7da53025..ecbae68fe2 100644 --- a/phpBB/docs/coding-guidelines.html +++ b/phpBB/docs/coding-guidelines.html @@ -35,7 +35,9 @@ -

These are the phpBB Coding Guidelines for Ascraeus, all attempts should be made to follow them as closely as possible.

+

+ These are the phpBB Coding Guidelines for Ascraeus, all attempts should be made to follow them as closely as possible. +

Coding Guidelines

-- cgit v1.2.1 From 4df853abccd48d89e1dfce6dfc1a0b9c5a34c7ee Mon Sep 17 00:00:00 2001 From: Cesar G Date: Tue, 23 Sep 2014 15:12:05 -0700 Subject: [ticket/12599] Remove empty line at end of code boxes. PHPBB3-12599 --- phpBB/docs/coding-guidelines.html | 367 +++++++++++++++++++------------------- 1 file changed, 183 insertions(+), 184 deletions(-) (limited to 'phpBB/docs/coding-guidelines.html') diff --git a/phpBB/docs/coding-guidelines.html b/phpBB/docs/coding-guidelines.html index ecbae68fe2..4c5fe73543 100644 --- a/phpBB/docs/coding-guidelines.html +++ b/phpBB/docs/coding-guidelines.html @@ -111,8 +111,8 @@ 
 {TAB}$mode{TAB}{TAB}= $request->variable('mode', '');
-{TAB}$search_id{TAB}= $request->variable('search_id', '');
-
+{TAB}$search_id{TAB}= $request->variable('search_id', ''); +

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

@@ -135,8 +135,8 @@ * For full copyright and license information, please see * the docs/CREDITS.txt file. * -*/ -
+*/ +

Please see the File Locations section for the correct package name.

@@ -159,8 +159,8 @@ /** */ -{CODE} -
+{CODE} +

Files containing only functions:

@@ -187,8 +187,8 @@ Small code snipped, mostly one or two defines or an if statement /** * {DOCUMENTATION} */ -class ... -
+class ... +

1.iii. File Locations

@@ -319,8 +319,8 @@ for ($i = 0; $i < $outer_size; $i++) { foo($i, $j); } -} -
+} +

Function Names:

Functions should also be named descriptively. We're not programming in C here, we don't want to write functions called things like "stristr()". Again, all lower-case names with words separated by a single underscore character in PHP, and camel caps in JavaScript. Function names should be prefixed with "phpbb_" and preferably have a verb in them somewhere. Good function names are phpbb_print_login_status(), phpbb_get_user_data(), etc. Constructor functions in JavaScript should begin with a capital letter.

@@ -346,14 +346,14 @@ phpbb/ dir/ class_name.php subdir/ - class_name.php - + class_name.php + 
 \phpbb\class_name            - phpbb/class_name.php
 \phpbb\dir\class_name        - phpbb/dir/class_name.php
-\phpbb\dir\subdir\class_name - phpbb/dir/subdir/class_name.php
-
+\phpbb\dir\subdir\class_name - phpbb/dir/subdir/class_name.php +

Summary:

@@ -379,8 +379,8 @@ while (condition) do_stuff(); for ($i = 0; $i < size; $i++) - do_stuff($i); - + do_stuff($i); +

// These are all right. 

@@ -397,8 +397,8 @@ while (condition)
 for ($i = 0; $i < size; $i++)
 {
 	do_stuff();
-}
-
+} +

Where to put the braces:

In PHP code, braces always go on their own line. The closing brace should also always be at the same column as the corresponding opening brace, examples:

@@ -429,8 +429,8 @@ while (condition) function do_stuff() { ... -} - +} +

In JavaScript code, braces always go on the same line:

@@ -453,8 +453,8 @@ while (condition) { function do_stuff() { ... -} - +} +

Use spaces between tokens:

This is another simple, easy step that helps keep code readable without much effort. Whenever you write an assignment, expression, etc.. Always leave one space between the tokens. Basically, write code as if it was English. Put spaces between variable names and operators. Don't put spaces just after an opening bracket or before a closing bracket. Don't put spaces just before a comma or a semicolon. This is best shown with a few examples, examples:

@@ -478,26 +478,26 @@ for($i=0; $i<$size; $i++) ... for ($i = 0; $i < $size; $i++) ... $i=($j < $size)?0:1; -$i = ($j < $size) ? 0 : 1; - +$i = ($j < $size) ? 0 : 1; +

Operator precedence:

Do you know the exact precedence of all the operators in PHP? Neither do I. Don't guess. Always make it obvious by using brackets to force the precedence of an equation so you know what it does. Remember to not over-use this, as it may harden the readability. Basically, do not enclose single expressions. Examples:

// what's the result? who knows.

- 
-$bool = ($i < 7 && $j > 8 || $k == 4);
-
+
+ 
$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:

There are two different ways to quote strings in PHP - either with single quotes or with double quotes. The main difference is that the parser does variable interpolation in double-quoted strings, but not in single quoted strings. Because of this, you should always use single quotes unless you specifically need variable interpolation to be done on that string. This way, we can save the parser the trouble of parsing a bunch of strings where no interpolation needs to be done.

@@ -507,25 +507,25 @@ $bool = ($i < 7 && ($j < 8 || $k == 4)); 
 $str = "This is a really long string with no variables for the parser to find.";
 
-do_stuff("$str");
-
+do_stuff("$str"); +

// right

 $str = 'This is a really long string with no variables for the parser to find.';
 
-do_stuff($str);
-
+do_stuff($str); +

// Sometimes single quotes are just not right

-$post_url = $phpbb_root_path . 'posting.' . $phpEx . '?mode=' . $mode . '&amp;start=' . $start;
-
+$post_url = $phpbb_root_path . 'posting.' . $phpEx . '?mode=' . $mode . '&amp;start=' . $start; +

// Double quotes are sometimes needed to not overcrowd the line with concatenations.

-$post_url = "{$phpbb_root_path}posting.$phpEx?mode=$mode&amp;start=$start";
-
+$post_url = "{$phpbb_root_path}posting.$phpEx?mode=$mode&amp;start=$start"; +

In SQL statements mixing single and double quotes is partly allowed (following the guidelines listed here about SQL formatting), else one should try to only use one method - mostly single quotes.

@@ -537,40 +537,40 @@ $post_url = "{$phpbb_root_path}posting.$phpEx?mode=$mode&amp;start=$start"; $foo = array( 'bar' => 42, 'boo' => 23 -); - +); +

// right 

 $foo = array(
 	'bar' => 42,
 	'boo' => 23,
-);
-
+); +

Associative array keys:

In PHP, it's legal to use a literal string as a key to an associative array without quoting that string. We don't want to do this -- the string should always be quoted to avoid confusion. Note that this is only when we're using a literal, not when we're using a variable, examples:

// wrong

- 
-$foo = $assoc_array[blah];
-
+
+ 
$foo = $assoc_array[blah];
+

// right

- 
-$foo = $assoc_array['blah'];
-
+
+ 
$foo = $assoc_array['blah'];
+

// wrong

- 
-$foo = $assoc_array["$var"];
-
+
+ 
$foo = $assoc_array["$var"];
+

// right

- 
-$foo = $assoc_array[$var];
-
+
+ 
$foo = $assoc_array[$var];
+

Comments:

Each complex function should be preceded by a comment that tells a programmer everything they need to know to use that function. The meaning of every parameter, the expected input, and the output are required as a minimal comment. The function's behaviour in error conditions (and what those error conditions are) should also be present - but mostly included within the comment about the output.

Especially important to document are any assumptions the code makes, or preconditions for its proper operation. Any one of the developers should be able to look at any part of the application and figure out what's going on in a reasonable amount of time.

Avoid using /* */ comment blocks for one-line comments, // should be used for one/two-liners.

@@ -584,8 +584,8 @@ $foo = $assoc_array[$var];

// wrong 

 $array[++$i] = $j;
-$array[$i++] = $k;
-
+$array[$i++] = $k; +

// right 

@@ -593,39 +593,38 @@ $i++;
 $array[$i] = $j;
 
 $array[$i] = $k;
-$i++;
-
+$i++; +

Inline conditionals:

Inline conditionals should only be used to do very simple things. Preferably, they will only be used to do assignments, and not for function calls or anything complex at all. They can be harmful to readability if used incorrectly, so don't fall in love with saving typing by using them, examples:

// Bad place to use them

-($i < $size && $j > $size) ? do_stuff($foo) : do_stuff($bar);
-
+($i < $size && $j > $size) ? do_stuff($foo) : do_stuff($bar); +

// OK place to use them 

-$min = ($i < $j) ? $i : $j;
-
+$min = ($i < $j) ? $i : $j; +

Don't use uninitialized variables.

For phpBB3, we intend to use a higher level of run-time error reporting. This will mean that the use of an uninitialized variable will be reported as a warning. These warnings can be avoided by using the built-in isset() function to check whether a variable has been set - but preferably the variable is always existing. For checking if an array has a key set this can come in handy though, examples:

// Wrong

- 
-if ($forum) ...
-
+
+ 
if ($forum) ...
+

// Right

- 
-if (isset($forum)) ...
-
+
+ 
if (isset($forum)) ...

// Also possible

- 
-if (isset($forum) && $forum == 5)
-
+
+ 
if (isset($forum) && $forum == 5)
+

The empty() function is useful if you want to check if a variable is not set or being empty (an empty string, 0 as an integer or string, NULL, false, an empty array or a variable declared, but without a value in a class). Therefore empty should be used in favor of isset($array) && sizeof($array) > 0 - this can be written in a shorter way as !empty($array).

@@ -642,8 +641,8 @@ switch ($mode) case 'mode2': // I am doing something completely different here break; -} - +} +

// Good 

@@ -660,8 +659,8 @@ switch ($mode)
 	default:
 		// Always assume that a case was not caught
 	break;
-}
-
+} +

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

@@ -684,8 +683,8 @@ switch ($mode)
 		// Always assume that a case was not caught
 
 	break;
-}
-
+} +

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

@@ -712,8 +711,8 @@ switch ($mode) // Always assume that a case was not caught break; -} - +} +

Class Members

Use the explicit visibility qualifiers public, private and protected for all properties instead of var. @@ -723,14 +722,14 @@ switch ($mode)

//Wrong 

 var $x;
-private static function f()
-
+private static function f() +

// Right 

 public $x;
-static private function f()
-
+static private function f() +

Constants

Prefer class constants over global constants created with define().

@@ -750,8 +749,8 @@ $sql = 'SELECT * <-one tab->WHERE a = 1 <-two tabs->AND (b = 2 <-three tabs->OR b = 3) -<-one tab->ORDER BY b'; - +<-one tab->ORDER BY b'; +

Here the example with the tabs applied:

@@ -761,8 +760,8 @@ $sql = 'SELECT * WHERE a = 1 AND (b = 2 OR b = 3) - ORDER BY b'; - + ORDER BY b'; +

SQL Quotes:

Use double quotes where applicable. (The variables in these examples are typecasted to integers beforehand.) Examples:

@@ -771,16 +770,16 @@ $sql = 'SELECT * 
 "UPDATE " . SOME_TABLE . " SET something = something_else WHERE a = $b";
 
-'UPDATE ' . SOME_TABLE . ' SET something = ' . $user_id . ' WHERE a = ' . $something;
-
+'UPDATE ' . SOME_TABLE . ' SET something = ' . $user_id . ' WHERE a = ' . $something; +

// These are right. 

 'UPDATE ' . SOME_TABLE . " SET something = something_else WHERE a = $b";
 
-'UPDATE ' . SOME_TABLE . " SET something = $user_id WHERE a = $something";
-
+'UPDATE ' . SOME_TABLE . " SET something = $user_id WHERE a = $something"; +

In other words use single quotes where no variable substitution is required or where the variable involved shouldn't appear within double quotes. Otherwise use double quotes.

@@ -791,15 +790,15 @@ $sql = 'SELECT * 
 $sql = 'SELECT *
 	FROM ' . SOME_TABLE . '
-	WHERE a != 2';
-
+ WHERE a != 2'; +

// This is right. 

 $sql = 'SELECT *
 	FROM ' . SOME_TABLE . '
-	WHERE a <> 2';
-
+ WHERE a <> 2'; +

Common DBAL methods:

@@ -810,8 +809,8 @@ $sql = 'SELECT * 
 $sql = 'SELECT *
 	FROM ' . SOME_TABLE . "
-	WHERE username = '" . $db->sql_escape($username) . "'";
-
+ WHERE username = '" . $db->sql_escape($username) . "'"; +

sql_query_limit():

@@ -832,8 +831,8 @@ $sql_ary = array( 'moredata' => $another_int, ); -$db->sql_query('INSERT INTO ' . SOME_TABLE . ' ' . $db->sql_build_array('INSERT', $sql_ary)); - +$db->sql_query('INSERT INTO ' . SOME_TABLE . ' ' . $db->sql_build_array('INSERT', $sql_ary)); +

To complete the example, this is how an update statement would look like:

@@ -847,8 +846,8 @@ $sql_ary = array( $sql = 'UPDATE ' . SOME_TABLE . ' SET ' . $db->sql_build_array('UPDATE', $sql_ary) . ' WHERE user_id = ' . (int) $user_id; -$db->sql_query($sql); - +$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), UPDATE (example above) and SELECT (for building WHERE statement [AND logic]).

@@ -871,8 +870,8 @@ $sql_ary[] = array( 'moredata' => $another_int_2, ); -$db->sql_multi_insert(SOME_TABLE, $sql_ary); - +$db->sql_multi_insert(SOME_TABLE, $sql_ary); +

sql_in_set():

@@ -882,22 +881,22 @@ $db->sql_multi_insert(SOME_TABLE, $sql_ary); $sql = 'SELECT * FROM ' . FORUMS_TABLE . ' WHERE ' . $db->sql_in_set('forum_id', $forum_ids); -$db->sql_query($sql); - +$db->sql_query($sql); +

Based on the number of values in $forum_ids, the query can look differently.

// SQL Statement if $forum_ids = array(1, 2, 3);

-SELECT FROM phpbb_forums WHERE forum_id IN (1, 2, 3)
-
+SELECT FROM phpbb_forums WHERE forum_id IN (1, 2, 3) +

// SQL Statement if $forum_ids = array(1) or $forum_ids = 1

-SELECT FROM phpbb_forums WHERE forum_id = 1
-
+SELECT FROM phpbb_forums WHERE forum_id = 1 +

Of course the same is possible for doing a negative match against a number of values:

@@ -905,22 +904,22 @@ SELECT FROM phpbb_forums WHERE forum_id = 1 $sql = 'SELECT * FROM ' . FORUMS_TABLE . ' WHERE ' . $db->sql_in_set('forum_id', $forum_ids, true); -$db->sql_query($sql); - +$db->sql_query($sql); +

Based on the number of values in $forum_ids, the query can look differently here too.

// SQL Statement if $forum_ids = array(1, 2, 3);

-SELECT FROM phpbb_forums WHERE forum_id NOT IN (1, 2, 3)
-
+SELECT FROM phpbb_forums WHERE forum_id NOT IN (1, 2, 3) +

// SQL Statement if $forum_ids = array(1) or $forum_ids = 1

-SELECT FROM phpbb_forums WHERE forum_id <> 1
-
+SELECT FROM phpbb_forums WHERE forum_id <> 1 +

If the given array is empty, an error will be produced.

@@ -950,8 +949,8 @@ $sql_array = array( 'ORDER_BY' => 'left_id', ); -$sql = $db->sql_build_query('SELECT', $sql_array); - +$sql = $db->sql_build_query('SELECT', $sql_array); +

The possible first parameter for sql_build_query() is SELECT or SELECT_DISTINCT. As you can see, the logic is pretty self-explaining. For the LEFT_JOIN key, just add another array if you want to join on to tables for example. The added benefit of using this construct is that you are able to easily build the query statement based on conditions - for example the above LEFT_JOIN is only necessary if server side topic tracking is enabled; a slight adjustement would be:

@@ -986,8 +985,8 @@ else // Here we read the cookie data } -$sql = $db->sql_build_query('SELECT', $sql_array); - +$sql = $db->sql_build_query('SELECT', $sql_array); +

2.iv. Optimizations

@@ -999,16 +998,16 @@ $sql = $db->sql_build_query('SELECT', $sql_array); for ($i = 0; $i < sizeof($post_data); $i++) { do_something(); -} - +} +

// You are able to assign the (not changing) result within the loop itself

 for ($i = 0, $size = sizeof($post_data); $i < $size; $i++)
 {
 	do_something();
-}
-
+} +

Use of in_array():

Try to avoid using in_array() on huge arrays, and try to not place them into loops if the array to check consist of more than 20 entries. in_array() can be very time consuming and uses a lot of cpu processing time. For little checks it is not noticeable, but if checked against a huge array within a loop those checks alone can take several seconds. If you need this functionality, try using isset() on the arrays keys instead, actually shifting the values into keys and vice versa. A call to isset($array[$var]) is a lot faster than in_array($var, array_keys($array)) for example.

@@ -1030,29 +1029,29 @@ for ($i = 0, $size = sizeof($post_data); $i < $size; $i++)

// Old method, do not use it

 $start = (isset($HTTP_GET_VARS['start'])) ? intval($HTTP_GET_VARS['start']) : intval($HTTP_POST_VARS['start']);
-$submit = (isset($HTTP_POST_VARS['submit'])) ? true : false;
-
+$submit = (isset($HTTP_POST_VARS['submit'])) ? true : false; +

// Use request var and define a default variable (use the correct type)

 $start = $request->variable('start', 0);
-$submit = $request->is_set_post('submit');
-
+$submit = $request->is_set_post('submit'); +

// $start is an int, the following use of $request->variable() therefore is not allowed

-$start = $request->variable('start', '0');
-
+$start = $request->variable('start', '0'); +

// Getting an array, keys are integers, value defaults to 0

-$mark_array = $request->variable('mark', array(0));
-
+$mark_array = $request->variable('mark', array(0)); +

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

-$action_ary = $request->variable('action', array('' => 0));
-
+$action_ary = $request->variable('action', array('' => 0)); +

Login checks/redirection:

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

@@ -1075,8 +1074,8 @@ $action_ary = $request->variable('action', array('' => 0)); { trigger_error('FORM_INVALID'); } - } - + } +

The string passed to add_form_key() needs to match the string passed to check_form_key(). Another requirement for this to work correctly is that all forms include the {S_FORM_TOKEN} template variable.

@@ -1087,8 +1086,8 @@ $action_ary = $request->variable('action', array('' => 0)); 
 $user->session_begin();
 $auth->acl($user->data);
-$user->setup();
-
+$user->setup(); +

The $user->setup() call can be used to pass on additional language definition and a custom style (used in viewforum).

@@ -1096,16 +1095,16 @@ $user->setup();

All messages/errors should be outputted by calling trigger_error() using the appropriate message type and language string. Example:

-trigger_error('NO_FORUM');
-
+trigger_error('NO_FORUM'); + 
-trigger_error($user->lang['NO_FORUM']);
-
+trigger_error($user->lang['NO_FORUM']); + 
-trigger_error('NO_MODE', E_USER_ERROR);
-
+trigger_error('NO_MODE', E_USER_ERROR); +

Url formatting

@@ -1114,8 +1113,8 @@ trigger_error('NO_MODE', E_USER_ERROR);

The append_sid() function from 2.0.x is available too, though it does not handle url alterations automatically. Please have a look at the code documentation if you want to get more details on how to use append_sid(). A sample call to append_sid() can look like this:

-append_sid("{$phpbb_root_path}memberlist.$phpEx", 'mode=group&amp;g=' . $row['group_id'])
-
+append_sid("{$phpbb_root_path}memberlist.$phpEx", 'mode=group&amp;g=' . $row['group_id']) +

General function usage:

@@ -1195,8 +1194,8 @@ phpbb_version = 3.1.0 # Parent style # Set value to empty or to this style's name if this style does not have a parent style -parent = prosilver - +parent = prosilver +

3.2. General Styling Rules

Templates should be produced in a consistent manner. Where appropriate they should be based off an existing copy, e.g. index, viewforum or viewtopic (the combination of which implement a range of conditional and variable forms). Please also note that the indentation and coding guidelines also apply to templates where possible.

@@ -2358,8 +2357,8 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2)) 'PAGE_OF' => 'Page %s of %s', /* Just grabbing the replacements as they come and hope they are in the right order */ - ... - + ... +

… a clearer way to show explicit replacement ordering is to do:

@@ -2368,8 +2367,8 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2)) 'PAGE_OF' => 'Page %1$s of %2$s', /* Explicit ordering of the replacements, even if they are the same order as English */ - ... - + ... +

Why bother at all? Because some languages, the string transliterated back to English might read something like:

@@ -2378,8 +2377,8 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2)) 'PAGE_OF' => 'Total of %2$s pages, currently on page %1$s', /* Explicit ordering of the replacements, reversed compared to English as the total comes first */ - ... - + ... +

6.iv. Using plurals

@@ -2397,8 +2396,8 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2)) 
 	...
 	$user->lang('NUMBER_OF_ELEPHANTS', $number_of_elephants);
-	...
-
+ ... +

And the English translation would be:

@@ -2409,8 +2408,8 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2)) 1 => 'You have 1 elephant', // Singular 2 => 'You have %d elephants', // Plural ), - ... - + ... +

While the Bosnian translation can have more cases:

@@ -2422,16 +2421,16 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2)) 2 => 'You have %d slona', // Used for 5, 6, 3 => ... ), - ... - + ... +

NOTE: It is okay to use plurals for an unknown number compared to a single item, when the number is not known and displayed:

 	...
 	'MODERATOR'	=> 'Moderator',  // Your board has 1 moderator
 	'MODERATORS'	=> 'Moderators', // Your board has multiple moderators
-	...
-
+ ... +

6.v. Writing Style

@@ -2445,8 +2444,8 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2)) ... 'CONV_ERROR_NO_AVATAR_PATH' => 'Note to developer: you must specify $convertor['avatar_path'] to use %s.', - ... - + ... +

// Good - Literal straight quotes should be escaped with a backslash, ie: \

@@ -2454,8 +2453,8 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2)) ... 'CONV_ERROR_NO_AVATAR_PATH' => 'Note to developer: you must specify $convertor[\'avatar_path\'] to use %s.', - ... - + ... +

However, because phpBB3 now uses UTF-8 as its sole encoding, we can actually use this to our advantage and not have to remember to escape a straight quote when we don't have to:

@@ -2464,24 +2463,24 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2)) 
 	...
 'USE_PERMISSIONS'	=>	'Test out user's permissions',
-	...
-
+ ... +

// Okay - However, non-programmers wouldn't type "user\'s" automatically

 	...
 'USE_PERMISSIONS'	=>	'Test out user\'s permissions',
-	...
-
+ ... +

// Best - Use the Unicode Right-Single-Quotation-Mark character

 	...
 'USE_PERMISSIONS'	=>	'Test out user’s permissions',
-	...
-
+ ... +

The " (straight double quote), < (less-than sign) and > (greater-than sign) characters can all be used as displayed glyphs or as part of HTML markup, for example:

@@ -2491,8 +2490,8 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2)) ... 'FOO_BAR' => 'PHP version < 5.3.3.<br /> Visit "Downloads" at <a href="http://www.php.net/">www.php.net</a>.', - ... - + ... +

// Okay - No more invalid HTML, but "&quot;" is rather clumsy

@@ -2500,8 +2499,8 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2)) ... 'FOO_BAR' => 'PHP version &lt; 5.3.3.<br /> Visit &quot;Downloads&quot; at <a href="http://www.php.net/">www.php.net</a>.', - ... - + ... +

// Best - No more invalid HTML, and usage of correct typographical quotation marks

@@ -2509,8 +2508,8 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2)) ... 'FOO_BAR' => 'PHP version &lt; 5.3.3.<br /> Visit “Downloads” at <a href="http://www.php.net/">www.php.net</a>.', - ... - + ... +

Lastly, the & (ampersand) must always be entitised regardless of where it is used:

@@ -2519,16 +2518,16 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2)) 
 	...
 'FOO_BAR'	=>	'<a href="http://somedomain.tld/?foo=1&bar=2">Foo & Bar</a>.',
-	...
-
+ ... +

// Good - Valid HTML, amperands are correctly entitised in all cases

 	...
 'FOO_BAR'	=>	'<a href="http://somedomain.tld/?foo=1&amp;bar=2">Foo &amp; Bar</a>.',
-	...
-
+ ... +

As for how these charcters are entered depends very much on choice of Operating System, current language locale/keyboard configuration and native abilities of the text editor used to edit phpBB language files. Please see http://en.wikipedia.org/wiki/Unicode#Input_methods for more information.

-- cgit v1.2.1