phpBB Coding Standard Guidelines

From d525c3bc51bb30f2e2ea07abc087ce8ab0f71613 Mon Sep 17 00:00:00 2001 From: James Atkinson Date: Thu, 24 May 2001 20:09:11 +0000 Subject: Added docs dir and some docs. Also working on Template 'how-to' doc, will be added later git-svn-id: file:///svn/phpbb/trunk@320 89ea8834-ac86-4346-8a33-228a782c2dd0 --- phpBB/docs/codingstandards.htm | 310 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 310 insertions(+) create mode 100644 phpBB/docs/codingstandards.htm (limited to 'phpBB/docs/codingstandards.htm') diff --git a/phpBB/docs/codingstandards.htm b/phpBB/docs/codingstandards.htm new file mode 100644 index 0000000000..1810af5589 --- /dev/null +++ b/phpBB/docs/codingstandards.htm @@ -0,0 +1,310 @@ + + +phpBB Coding Standard Guidelines + + + +

phpBB Coding Standard Guidelines

Comments or suggestions? email nate@phpbb.com

Editor +Settings
Naming +Conventions
Code Layout
General +Guidelines

top +

Editor Settings

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.

top +

Naming Conventions

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().

top +

Code Layout

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$
+		
+		 ***************************************************************************/
+		
+		/***************************************************************************
+		 *                                         				                                
+		 *   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)
+

top +

General Guidelines

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)) ...
+

Return +to top -- cgit v1.2.1