Coding Guidelines

The purpose of this page is to establish a common set of coding guidelines to be used by all project contributors. Please familiarize yourself with the contents, most of which is common practice.

Please notify the team if you make changes to this page

This project generally follows established WordPress coding guidlines, with the following additions or exceptions.

File naming conventions

File names should follow these conventions to allow contributors to quickly identify file content type

Classes

The file name should represent the name of the class. One class per file! Upper first character, camel case

Example

UserModel.php

Function files

Lowercase with underscores seperating words

Example

helper_functions.php

Documentation ( Doc all the things )

Though code should be written in a self-documenting fashion it is always still helpful to write comments. Please write comments. If the code took you more than 1.36 seconds to determine in your head write a comment

Bonus points, PHPdoc is parsed by most IDEs and will help you contribute faster by not needing to look up the code :)

functions & methods

All functions and methods must have a PHP doc block associated with them. Please use standard PHPdoc syntax. PHPdoc documentation can be found at http://www.phpdoc.org/.

Required tags

@since - When the function or method was added to the project @param - If parameters exist @return - If value is returned

Classes

This project has lots of classes. To make it easier to read please use the following

Class name

Use upper first camel case notation. Keep in mind the class name and the file name should be the same

PHPdoc appreciated. At least the @since

Example

class UserRepository { ... }

Properties

Do not prefix with an underscore ( _ ) as it makes the magic getters and setters less friendly. Also it is an outdated convention from before PHP had native ability to mark properties private.

PHPdoc on properties is appreciated

Use lower first camel case notation Example

private $variableName;

Methods

Method names should be lower first camel case.

PHPdoc is required

Example

/**
 * Does some really cool stuff. You should use this method!
 *
 * @since 1.0
 * @param String $param - Used to do cool things
 * @return String - Result of cool things
 **/
public function doesCoolThings( $param ) {
    ...
    return $stuff;
}

Functions

Function names should be lower case with underscores ( _ ) between words.

PHPdoc is required

Example

/**
 * Does some really cool stuff. You should use this method!
 *
 * @since 1.0
 * @param String $param - Used to do cool things
 * @return String - Result of cool things
 **/
function does_cool_things( $param ) {
    ...
    return $stuff;
}