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. -
-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 Win32 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.
We will not be using any form of hungarian notation in our naming -conventions. Many of us believe that hungarian naming is one of the primary code -obfuscation techniques currently in use.
-Variable Names: Variable names should be in all lowercase, with words
-separated by an underscore.
Example: $current_user is right, but $currentuser and $currentUser are not.
Names should be descriptive,
-but concise. We don't want huge sentences as our variable names, but typing an
-extra couple of characters is always better than wondering what exactly a
-certain variable is for.
Loop Indices: The only situation where a one-character variable
-name is allowed is when it's the index for some looping construct. In this case,
-the index of the outer loop should always be $i. If there's a loop inside that
-loop, its index should be $j, followed by $k, and so on. If the loop is being
-indexed by some already-existing variable with a meaningful name, this guideline
-does not apply.
Example:
- for ($i = 0; $i < $outer_size; $i++)
- {
- for ($j = 0; $j < $inner_size; $j++)
- {
- 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. Function names should preferably have a verb in them
-somewhere. Good function names are print_login_status(), get_user_data(), etc..
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.
Summary: 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().
Standard header for new files: Here a template of the header that must -be included at the start of all phpBB files:
- /*************************************************************************** - filename.php - ------------------- - begin : Sat June 17 2000 - copyright : (C) 2000 The phpBB Group - email : support@phpBB.com - - $Id: codingstandards.htm,v 1.3 2001/06/09 21:00:12 natec Exp $ - - ***************************************************************************/ - - /*************************************************************************** - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; either version 2 of the License, or - * (at your option) any later version. - * - ***************************************************************************/ -- -
Always include the braces: This is another case of being too lazy to
-type 2 extra characters causing problems with code clarity. Even if the body of
-some construct is only one line long, do not drop the braces. Just don't.
-
Examples:
- /* These are all wrong. */
- if (condition) do_stuff();
- if (condition)
- do_stuff();
- while (condition)
- do_stuff();
- for ($i = 0; $i < size; $i++)
- do_stuff($i);
-
- /* These are right. */
- if (condition)
- {
- do_stuff();
- }
- while (condition)
- {
- do_stuff();
- }
- for ($i = 0; $i < size; $i++)
- {
- do_stuff();
- }
-
-
-Where to put the braces: This one is a bit of a holy war, but we're
-going to use a style that can be summed up in one sentence: Braces always go on
-their own line. The closing brace should also always be at the same column as
-the corresponding opening brace.
Examples:
- if (condition)
- {
- while (condition2)
- {
- ...
- }
- }
- else
- {
- ...
- }
-
- for ($i = 0; $i < $size; $i++)
- {
- ...
- }
-
- 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:
- /* Each pair shows the wrong way followed by the right way. */ - - $i=0; - $i = 0; - - if($i<7) ... - if ($i < 7) ... - - if ( ($i < 7)&&($j > 8) ) ... - if (($i < 7) && ($j > 8)) ... - - do_stuff( $i, "foo", $b ); - do_stuff($i, "foo", $b); - - for($i=0; $i<$size; $i++) ... - for($i = 0; $i < $size; $i++) ... - - $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.
-
Examples:
- /* what's the result? who knows. */ - $bool = ($i < 7 && $j > 8 || $k == 4); - - /* now you can be certain what I'm doing here. */ - $bool = (($i < 7) && (($j < 8) || ($k == 4))) -- -
SQL code layout: Since we'll all be using different editor settings,
-don't try to do anything complex like aligning columns in SQL code. Do, however,
-break statements onto their own lines. Here's a sample of how SQL code should
-look. Note where the lines break, the capitalization, and the use of brackets.
-
Examples:
- SELECT field1 AS something, field2, field3 - FROM table a, table b - WHERE (this = that) AND (this2 = that2) -- -
SQL insert statements: SQL INSERT statements can be written in two
-different ways. Either you specify explicitly the columns being inserted, or
-you rely on knowing the order of the columns in the database and do not
-specify them. We want to use the former approach, where it is explicitly
-stated whcih columns are being inserted. This means our application-level code
-will not depend on the order of the fields in the database, and will not be broken
-if we add additional fields (unless they're specified as NOT NULL, of course).
-
Examples:
- # This is not what we want.
- INSERT INTO mytable
- VALUES ('something', 1, 'else')
-
- # This is correct.
- INSERT INTO mytable (column1, column2, column3)
- VALUES ('something', 1, 'else')
-
-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. Also, if you are using a string
-variable as part of a function call, you do not need to enclose that variable in
-quotes. Again, this will just make unnecessary work for the parser. Note,
-however, that nearly all of the escape sequences that exist for double-quoted
-strings will not work with single-quoted strings. Be careful, and feel free to
-break this guideline if it's making your code harder to read.
-
Examples:
- /* wrong */
- $str = "This is a really long string with no variables for the parser to find.";
- do_stuff("$str");
-
- /* right */
- $str = 'This is a really long string with no variables for the parser to find.';
- do_stuff($str);
-
-
-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]; - - /* right */ - $foo = $assoc_array['blah']; -- -
Comments: Each 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. Nobody should have to look at the actual
-source of a function in order to be able to call it with confidence in their own
-code.
In addition, commenting any tricky, obscure, or otherwise
-not-immediately-obvious code is clearly something we should be doing. Especially
-important to document are any assumptions your 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.
Magic numbers: Don't use them. Use named constants for any literal -value other than obvious special cases. Basically, it's OK to check if an array -has 0 elements by using the literal 0. It's not OK to assign some special -meaning to a number and then use it everywhere as a literal. This hurts -readability AND maintainability. Included in this guideline is that we should be -using the constants TRUE and FALSE in place of the literals 1 and 0 -- even -though they have the same values, it's more obvious what the actual logic is -when you use the named constants.
-Shortcut operators: The only shortcut operators that cause readability
-problems are the shortcut increment ($i++) and decrement ($j--) operators. These
-operators should not be used as part of an expression. They can, however, be
-used on their own line. Using them in expressions is just not worth the
-headaches when debugging.
Examples:
- /* wrong */ - $array[++$i] = $j; - $array[$i++] = $k; - - - /* right */ - $i++; - $array[$i] = $j; - - $array[$i] = $k; - $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); - - - /* OK place to use them */ - $min = ($i < $j) ? $i : $j; -- -
Don't use uninitialized variables. for phpBB 2, 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 an error. This will come up most
-often when checking which HTML form variables were passed. These errors can be
-avoided by using the built-in isset() function to check whether a variable has
-been set.
Examples:
- /* Old way */ - if ($forum) ... - - - /* New way */ - if (isset($forum)) ... --