DocBlock

Every XML 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.

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 -->
<remove name="paypal" />

Short descriptions

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

<!-- GravDept: hide PayPal. -->
<remove name="paypal" />

Long descriptions

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

<!--
GravDept:
Lorem ipsum dolor sit amet.
-->
<remove name="paypal" />

Referencing URLs and files

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

<!--
GravDept:
Lorem ipsum dolor sit amet.
See: paypal.xml
-->
<remove name="paypal" />

Tasks

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

<!-- GravDept: [refactor] -->
<!-- GravDept: [todo] -->