Joomla! 编码规范
DocBlocks
关于
编码规范
客户端语法风格指南
附录
PHP 代码中的文档头，包括文件、类、类属性、方法和函数，称为 docblocks，遵循与 JavaDoc 或 phpDOC 类似的约定。
这些“DocBlocks”借鉴了 PEAR 标准，但对 Joomla 和 Joomla 项目有一些特定变化。
虽然正常的代码缩进使用真实的制表符，但在 Docblock 中所有空白都使用实际的空格。这在源代码浏览器中提供了更好的可读性。任何文本元素（如标签、变量类型、变量名称和标签描述）之间的最小空格为两个实际空格。变量类型和标签描述应根据最长的 Docblock 标签和类型加变量分别对齐。
贡献给 Joomla 项目并成为项目版权的代码不允许包含 @author 标签。Joomla 的理念是代码是“一起编写”的，不存在任何一个人“拥有”代码的任何部分的概念。 @author 标签允许在核心库中包含的第三方库中使用。
从第三方来源包含的文件必须保持 DocBlocks 完好无损。布局文件使用与其他 PHP 文件相同的 DocBlocks。
文件 DocBlock 头
文件头 DocBlock 包含以下必需和可选元素，顺序如下
简短描述（可选，除非文件包含两个以上类或函数），后跟一个空行）。长描述（可选，后跟一个空行）。
- @Version（可选，必须是第一个）
- @category（可选，很少使用）
- @Package（通常可选，但当文件仅包含过程代码时必须使用。在命名空间代码中始终可选）
- @subpackage（可选）
- @author（可选，但仅允许在非 Joomla 源文件中使用）
- @copyright（必需）
- @license（必需，并且必须与 Joomla 许可证兼容）
- @link（可选）
- @see（可选）
- @SInCE（通常可选，但当文件仅包含过程代码时必须使用）
- @deprecated（可选）
DocBlock 头的示例
/**
* @package Joomla.Installation
* @subpackage Controller
*
* @copyright Copyright (C) 2005 - 2014 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/类定义
类定义从新行开始，开括号和闭括号也放置在新行上。类方法必须遵循函数定义的指南。属性和方法必须遵循 OOP 标准，并适当地声明（使用 public、protected、private 和 static，视情况而定）。类定义、属性和方法必须分别提供 DocBlock，以符合以下部分。
类 DocBlock 头
类 Docblock 包含以下必需和可选元素，顺序如下。
简短描述（必需，除非文件包含两个以上类或函数），后跟一个空行）。长描述（可选，后跟一个空行）。
- @category（可选，很少使用）
- @Package（可选）
- @subpackage（可选）
- @author（可选，但仅允许在非 Joomla 源文件中使用）
- @copyright（可选，除非与文件 Docblock 不同）
- @license（可选，除非与文件 Docblock 不同）
- @link（可选）
- @see（可选）
- @SInCE（必需，即引入类的软件版本）
- @deprecated（可选）
类文件 DocBlock 头的示例
/**
* Controller class to initialise the database for the Joomla Installer.
*
* @package Joomla.Installation
* @subpackage Controller
* @since 3.1
*/类属性 DocBlocks
类属性 Docblock 包含以下必需和可选元素，顺序如下。
简短描述（必需，后跟一个空行）
- @var（必需，后跟属性类型）
- @SInCE（必需）
- @deprecated（可选）
类属性 DocBlock 的示例
/**
* The generated user ID
*
* @var integer
* @since 3.1
*/
protected static $userId = 0;类方法 DocBlocks 和函数 DocBlocks
函数定义从新行开始，开括号和闭括号也放置在新行上。指定返回值的行之前应该有一个空行。
函数定义必须包含符合本文档注释部分的文档注释。
- 简短描述（必需，后跟一个空行）
- 长描述（可选，后跟一个空行）
- @param（如果存在方法或函数参数，则最后一个 @param 标签后跟一个空行）
- @return（必需，后跟一个空行）
- @SInCE（必需，如果存在其他标签，则后跟一个空行）
- @throws（如果方法或函数参数抛出特定类型的异常，则必需）
- 所有其他标签按字母顺序排列。
注意
通常，@param 标签后的行按出现顺序包含以下三部分
- 变量类型（变量类型之前必须有 3 个空格。）
- 变量名称（最长类型之后必须有 2 个空格。）
- 变量描述（最长变量名称之后必须有 2 个空格。）
如果有多个 @param，则类型、名称和描述必须对齐。
方法 DocBlock 的示例
/**
* Set a controller class suffix for a given HTTP method.
*
* @param string $method The HTTP method for which to set the class suffix.
* @param string $suffix The class suffix to use when fetching the controller name for a given request.
*
* @return JApplicationWebRouter This object for method chaining.
*
* @since 12.2
*
* @throws InvalidArgumentException Thrown if the provided arguments is not of type string.
* @throws \UnexpectedValueException May be thrown if the container has not been set.
*/
public function setHttpMethodSuffix($method, $suffix)如果函数定义跨越多行，则所有行都必须缩进一个制表符，并且闭括号必须与最后一个参数位于同一行。
function fooBar($param1, $param2,
$param3, $param4)
{
// Body of method.
}