Table of Contents

• Introduction
• PHP
• Indenting
• Control Structures
• Function Calls
• Function Definitions
• Comments
• Including Code
• PHP Code Tags
• Naming Conventions
• Classes
• Functions and Methods
• Constants
• Global Variables
• Predefined Values
• SQL
• Formatting
• Naming Conventions
• Table Names
• Column Names
• Sequence Names
• Index Names

Introduction

These coding conventions follow a lot of the PEAR Coding Standards. In fact a lot of text, samples and even whole sections were just copied to the RSD Coding Conventions. Most important the RSD Coding Conventions do not forbid the use of tabs for indentation and do not require a comment header with a licence statement. But the RSD Coding Conventions as well include a section about writing SQL statements which the PEAR Coding Standards do not! These coding conventions are primarly meant for use in commercial projects - and not in open source projects. This is why they differ a bit from the PEAR Coding Standards.

PHP

Indenting

Put each statement on a seperate line and use an indent of 4 spaces or a tab. It cannot be said often enough: use indentation to make your code more readable. Just compare the two following code snippets.

1     class Test{
2     function Test($value){
3     if($value == "myvalue"){
4     $this->value = "perfect";
5     }else{ $value = "yo";;
6     }
7     }
8     function toString(){
9     if(is_string($this->value)){
10        return "invalid";
11    }else{ return $this->value;
12    }
13    }
14    }

Is the second function a method of the class Test or is it just an orinary function? Can you tell? - sure you can, but I think it was made clear why we need indentation. And here goes the well formated code:

1     class Test{
2         function Test($value){
3             if($value == "myvalue"){
4                 $this->value = "perfect";
5             }else{
6                 $value = "yo";;
7             } 
8             //end of constructor
9         }
10        
11        function toString(){
12            if(is_string($this->value)){
13                return "invalid";
14            }else{
15                return $this->value;
16            }
17            //end of method toString
18        }
19    }

Control Structures

These include if, for, while, switch, etc. Here is an example if statement, since it is the most complicated of them:

1     <?php
2     if ((condition1) || (condition2)) {
3         action1;
4     } elseif ((condition3) && (condition4)){
5         action2;
6     } else {
7         defaultaction;
8     }
9     ?>

Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls. Note that there is as well a space between the closing brace and the opening curly brace.

You are strongly encouraged to always use curly braces even in situations where they are technically optional. Having them increases readability and decreases the likelihood of logic errors being introduced when new lines are added.

1     <?php
2     switch (condition) {
3     case 1:
4         action1;
5         break;
6     case 2:
7         action2;
8         break;
9     default:
10        defaultaction;
11        break;
12    
13    }
14    ?>

In general an if statement should not go over multiple lines! But if the readability of your code gets very bad as in the following example

1     <?php
2     if (RSArrayUtil::hasElements($array1, $array2, $this->_subComparator) && RSArrayUtil::hasElements($array2, $array1, $this->_subComparator)) {
3         return 0;
4     }
5     ?>

you are allowed to write it like this:

1     <?php
2     if (
3             RSArrayUtil::hasElements($array1, $array2, $this->_subComparator)
4             &&
5             RSArrayUtil::hasElements($array2, $array1, $this->_subComparator)
6         )
7     {
8         return 0;
9     }
10    ?>

Try not to use this style if possible!

Function Calls

Functions should be called with no spaces between the function name, the opening parenthesis, and the first parameter; spaces between commas and each parameter, and no space between the last parameter, the closing parenthesis, and the semicolon. Here's an example:

1     <?php
2     $var = foo($bar, $baz, $quux);
3     ?>

As displayed above, there should be one space on either side of an equals sign used to assign the return value of a function to a variable. In the case of a block of related assignments, more space may be inserted to promote readability:

1     <?php
2     $short         = foo($bar);
3     $long_variable = foo($baz);
4     ?>

In general a function call should not go over multiple lines! But if the readability of your code gets very bad as in the following example

1     <?php
2     $io->copy($file1->parentDirectories[0]->getPathRelativeTo('/www/some/path/') . '_postfix/another/path/', $file2->parentDirectories[0]->getPathRelativeTo('/www/some/path/') . '_postfix/another/path/');
3     ?>

it is allowed to write it like this:

1     <?php
2     $io->copy(
3         $file1->parentDirectories[0]->getPathRelativeTo('/www/some/path/') . '_postfix/another/path/',
4         $file2->parentDirectories[0]->getPathRelativeTo('/www/some/path/') . '_postfix/another/path/');
5     ?>

Try not to use this style if possible!

Function Definitions

Function declarations should follow the "one true brace" convention.

1     <?php
2     function fooFunction($arg1, $arg2 = '')
3     {
4         if(condition){
5             statement;
6         }
7         return $val;
8     }
9     ?>

Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate. Here is a slightly longer example:

1     <?php
2     function connect(&$dsn, $persistent = false)
3     {
4         if (is_array($dsn)) {
5             $dsninfo = &$dsn;
6         } else {
7             $dsninfo = DB::parseDSN($dsn);
8         }
9     
10        if (!$dsninfo || !$dsninfo['phptype']) {
11            return $this->raiseError();
12        }
13    
14        return true;
15    }
16    ?>

Comments

Inline documentation for classes should follow the PHPDocumentor convention, similar to Javadoc.

Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works.

C style comments (/* */) and standard C++ comments (//) are both fine. Use of Perl/shell style comments (#) is discouraged.

Including Code

Anywhere you are unconditionally including a class file, use require_once(). Anywhere you are conditionally including a class file (for example, factory methods), use include_once(). Either of these will ensure that class files are included only once. They share the same file list, so you don't need to worry about mixing them - a file included with require_once() will not be included again by include_once().

PHP Code Tags

Always use

<?php ?>

to delimit PHP code, not the

<? ?>

shorthand. This is required for PEAR compliance and is also the most portable way to include PHP code on differing operating systems and setups. Please note that this means as well not to use the shorthand

<?=$variable?>

for

<?php echo $variable; ?>

. This should not be that bad because you are encouraged to use the template engine Smarty anyway.

Naming Conventions

The name of of any identifyer (function, method, class, variable, ...) should always be descriptive enough to easily tell the reader of the code what this identifyer stands for. Avoid using abbreviations where possible! It is very easy to mess up a good design with badly chosen identifyer names. Because no matter how good a design is, naming an identifyer "fn" that holds a person's first name or a table that stores product information "pr" will result in very hard to maintain and nearly unreadable code.

Classes

The first letter of the class name is uppercase, and each letter that starts a new "word" is capitalized as well. The lack of java-like packages can result in a clash of class names. Therefore it might be appropriate to prepend the package name to the class name. If you do so, it is allowed to seperate the the package name from the class name by a underscore (_). This is the only case in which underscores are allowed in class names. This results in the following format:

			[Packagename[_]]Classname
		

Examples:
• UserManagement
• Packagename_Login
• PackagenameAuth
• Permission



Functions and Methods

Functions and methods should be named using the "studly caps" style (also referred to as "bumpy case" or "camel caps"). Functions should in addition have the package name as a prefix, to avoid name collisions between packages. The initial letter of the name (after the prefix) is lowercase, and each letter that starts a new "word" is capitalized. Some examples:

• connect()
• getData()
• buildSomeWidget()
• PRJ_serializeData()

Private class members and properties (meaning class members and properties that are intented to be used only from within the same class in which they are declared; PHP does not yet support truly-enforceable private namespaces) are preceded by a single underscore. For example:

• _sort()
• _initTree()
• _status



Constants

Constants should always be all-uppercase, with underscores to separate words. Prefix constant names with the uppercased name of the class/package they are used in. For example, the constants used by the DB:: package all begin with "DB_".




Global Variables

The use of global variables is not recommended! If your package needs to define global variables, their name should start with a single underscore followed by the package name and another underscore. For example, the PEAR package uses a global variable called $_PEAR_destructor_object_list.




Predefined Values

PHP's built-in values true, false and null must be written in lower-case.




SQL

Formatting

• All SQL identifyers are lowercase!
• SQL identifyers do not contain underscores (Note the exceptions below!)
• SQL kezwords like SELECT, UPDATE, INSERT, WHERE, FROM, GROUP BY are always uppercase!
• Use only single quotes (') in your query. This will make it compatible to Oracle and allows you to write code like the following:

  
  1     $db->query("
  2     	SELECT
  3     		*
  4     	FROM
  5     		table
  6     	WHERE
  7     		f_column = '$value'
  8     ";

The following formating is strongly recommended for writing SELECT-Queries:

SELECT
	econ_table1.f_field1,
	econ_table1.f_field2,
	econ_table2.f_field1
FROM
	econ_table1,
	econ_table2,
	econ_table3,
WHERE
	econ_table1.f_field7 = econ_table2.f_field1
	AND
	econ_table2.f_field4 = econ_table1.f_field3
	OR
		(
		econ_table1.f_field10 = '$field10'
		AND
		...
		)
	AND
	...

The following formating is strongly recommended for writing CREATE TABLE statements:

CREATE TABLE t_user(
	f_userid NUMBER PRIMARY KEY UNIQUE NOT NULL,
	f_group_id NUMBER,
	f_firstname VARCHAR(100),
	f_lastname VARCHAR(200),
	UNIQUE(f_firstname,f_lastname),
	FOREIGN KEY (f_group_id) REFERENCES(t_group.f_groupid)
);

Note:
• Each column is on a seperate line.
• The opening parenthesis is on the same line as the 'CREATE TABLE ...'
• The closing parenthesis followed by a semi-colon are the only characters on the last line.
• The primary key is defined as column constraint.
• The foreign key is defined as table constraint.
• The unique constraint that involves only one column is defined as column constraint.
• The unique constraint that involves more than one column is defined as table constraint.
• All tables are defined with a primary key!

Naming Conventions

The name of of any identifyer (function, method, class, variable, database table, column, sequence, ...) should always be descriptive enough to easily tell the reader of the code what this identifyer stands for. Avoid using abbreviations where possible! It is very easy to mess up a good design with badly chodesn identifyer names. Because no matter how good a design is, naming an identifyer "fn" that holds a person's first name or a table that stores product information "pr" will result in very hard to maintain and nearly unreadable code.

Table Names

Table names are always singular - this is just a convention but I guess it's obvious that the table t_user contains a lot of records. Table names consist of a project-specific prefix, a descriptive name and an underscore seperating these two. Example: a table of the project SPS (Sony Project Spaces) that holds login information for all users should be named

		sps_login
		




Column Names

• All columns have the following prefix: f_
• Even though it seems redundant (and in fact is) it sometimes makes sense to include the name of the countaining table in the column name. This is because when fetching records form a query joining multiple tables into an assocciative array with the column names as keys, one column might overwrite the other. If you do so, the table name (without prefix) is inserted between the prefix (f_) and the column name. Example: the column f_id of the table sps_login becomes f_loginid.
• Foreign keys consist of the prefix "f_", the table name containing the referenced primary key (without prefix!), an underscore and the name of the primary key without its prefix. Example: a foreign key that points to the column f_loginid of the table sps_login would be named

  			f_login_id
  			




Sequence Names

The following format is strongly recommended:

seq_<project_prefix>_<table_name>_<column_name>

A sequence for prj_user.f_userid (Note: the project prefix is prj) would be named

seq_prj_user_userid




Index Names

The following format is strongly recommended:

idx_<project_prefix>_<table_name>_<column_name>

An index for prj_user.f_userid (Note: the project prefix is prj) would be named

idx_prj_user_userid