Coding Standards

sameAs Lite source code must comply with the following coding standards:

• PHP Framework Interop Group Basic coding standard (PSR1)
• PHP Framework Interop Group Coding style guide (PSR2)
• No unused function parameters.
• No FIXME comments.
• No TODO comments.

Commenting code

Every class, function, and member variable must be commented. phpDocumentor comments and tags are used so that API documentation can be auto-generated from the source code.

An example class comment is:

/**
 * SameAs Lite
 *
 * This class provides a specialised storage capability for SameAs pairs.
 *
 * @package   SameAsLite
 * @author    Seme4 Ltd <sameAs@seme4.com>
 * @copyright 2009 - 2014 Seme4 Ltd
 * @link      http://www.seme4.com
 * @version   0.0.1
 * @license   MIT Public License
 * ...
 */

An example member variable comment is:

/** @var \PDO $dbHandle The PDO object for the DB, once opened */
protected $dbHandle;

Example function comments are:

/**
 * Establish connection to database, if not already made
 *
 * @throws \Exception Exception is thrown if connection fails or table cannot be accessed/created.
 */
public function connect()
...

/**
 * This is the simple method to query a store with a symbol
 *
 * Looks up the given symbol in a store, and returns the bundle with all
 * the symbols in it (including the one given). The bundle is ordered with
 * canon(s) first, then non-canons, in alpha order of symbols.
 *
 * @param string $symbol The symbol to be looked up
 * @return string[] An array of the symbols, which is singleton of the given symbol of nothing was found
 */
public function querySymbol($symbol)
...

For more on phpDocumentor comments and tags, see Learn about phpDocumentor especially the sections:

• Your First Set of Documentation
• Inside DocBlocks

How style checking works

When make checks is run, two passes are done:

1. PHP Code Beautifier and Fixer (phpcbf) is run to identify deviations from the coding style, and to fix these if possible.
2. PHP_CodeSniffer (phpcs) is run to identify and report on any remaining deviations from the coding style.

PHP_CodeSniffer configuration files are in dev-tools/CodeStandard. For more information on these see PHP_CodeSniffer documentation and files:

• Coding Standard Tutorial
• Annotated ruleset.xml
• Built-in coding standards