DocBlock

Every PHP file should lead with a DocBlock. Replace the {template} values with actual content.

/**
* {projectName}
* {projectDescription}
*
* @author    {authorName} ({authorWebsite})
* @package   {packageDesignation}
* @copyright Copyright {year} {copyrightHolderName}
* @license   All rights reserved.
*/

Here’s an example DocBlock for GravDept:

/**
* Gravity Department
* Responsive frontend site
*
* @author    Brendan Falkowski (http://gravitydept.com)
* @package   gravdept
* @copyright Copyright 2014 Gravity Department
* @license   All rights reserved.
*/

• Don’t put a space before the leading * character.
• Leave two empty lines after a page DocBlock.

Single-line comments

Use single-line comments // comment instead of multi-line comments /* comment */. This lets you easily span multi-line comments over single-line comments.

// Single-line comments applicable to following line.
$x = ($i > 5) ? 'banana' : 'apple';

// Single-line comment applicable to group of code.

$x = ($i > 5) ? 'banana' : 'apple';

return $x;

Multi-line comments

Only use multi-line comments when the code spans multiple lines, or contains single-line comments within.

/*
if ($apple) {
    return $apple;
} else {
    // Bananas are better.
    return $banana;
}
*/

Signing comments

Signing comments improves communication in teams and documentation. In platform code, it separates system comments from implementor comments.

Simple signing

Just a small flag to identify a change from vendor code that could easily be overlooked.

// GravDept
$i = 0;

Short descriptions

Use colon after signature. Treat entire line as a sentence.

// GravDept: reset counter.
$i = 0;

Long descriptions

Use a colon after the namespace. Write one sentence per line. Use punctuation. Lines longer than ~80 characters should be wrapped.

// GravDept:
// Initialize the application.
// This bootstraps the necessary libraries.
init();

Referencing URLs

Typically the last line in a comment block. If multiple, put each URL on its own line.

// GravDept:
// Lorem ipsum dolor sit amet.
// See: http://gravitydept.com/some/reference
$i = 0;

Tasks

Use comment [flags] to mark code that needs future attention. These are easy to search for later.

// GravDept: [refactor]
// The reason you need to rewrite.

// GravDept: [testing]
//var_dump($data);

// GravDept: [todo]
// The thing you need to do.