Code Style#
The following code style conventions are used by us for our own packages. While you do not have to follow every rule, you are encouraged to do so.
For information about how to document your code, please refer to the documentation page.
General Code Style#
Naming conventions#
The relevant naming conventions are:
- Upper camel case: The first letters of all compound words are written in upper case.
- Lower camel case: The first letters of compound words are written in upper case, except for the first letter which is written in lower case.
- Screaming snake case: All letters are written in upper case and compound words are separated by underscores.
Type | Convention | Example |
---|---|---|
Variable | lower camel case | $variableName |
Class | upper camel case | class UserGroupEditor |
Properties | lower camel case | public $propertyName |
Method | lower camel case | public function getObjectByName() |
Constant | screaming snake case | MODULE_USER_THING |
Arrays#
For arrays, use the short array syntax introduced with PHP 5.4. The following example illustrates the different cases that can occur when working with arrays and how to format them:
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
Ternary Operator#
The ternary operator can be used for short conditioned assignments:
1 2 3 |
|
The condition and the values should be short so that the code does not result in a very long line which thus decreases the readability compared to an if-else
statement.
Parentheses may only be used around the condition and not around the whole statement:
1 2 3 4 |
|
Parentheses around the conditions may not be used to wrap simple function calls:
1 2 3 4 |
|
but have to be used for comparisons or other binary operators:
1 2 3 |
|
If you need to use more than one binary operator, use an if-else
statement.
The same rules apply to assigning array values:
1 2 3 4 5 6 7 |
|
or return values:
1 2 3 |
|
Whitespaces#
You have to put a whitespace in front of the following things:
- equal sign in assignments:
$x = 1;
- comparison operators:
$x == 1
- opening bracket of a block
public function test() {
You have to put a whitespace behind the following things:
- equal sign in assignments:
$x = 1;
- comparison operators:
$x == 1
- comma in a function/method parameter list if the comma is not followed by a line break:
public function test($a, $b) {
if
,for
,foreach
,while
:if ($x == 1)
Classes#
Referencing Class Names#
If you have to reference a class name inside a php file, you have to use the class
keyword.
1 2 3 4 5 6 7 8 |
|
Static Getters (of DatabaseObject
Classes)#
Some database objects provide static getters, either if they are decorators or for a unique combination of database table columns, like wcf\data\box\Box::getBoxByIdentifier()
:
Such methods should always either return the desired object or null
if the object does not exist.
wcf\system\database\statement\PreparedStatement::fetchObject()
already takes care of this distinction so that its return value can simply be returned by such methods.
The name of such getters should generally follow the convention get{object type}By{column or other description}
.
Long method calls#
In some instances, methods with many argument have to be called which can result in lines of code like this one:
1 2 3 |
|
which is hardly readable. Therefore, the line must be split into multiple lines with each argument in a separate line:
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
In general, this rule applies to the following methods:
wcf\system\edit\EditHistoryManager::add()
wcf\system\message\quote\MessageQuoteManager::addQuote()
wcf\system\message\quote\MessageQuoteManager::getQuoteID()
wcf\system\search\SearchIndexManager::set()
wcf\system\user\object\watch\UserObjectWatchHandler::updateObject()
wcf\system\user\notification\UserNotificationHandler::fireEvent()