[MANUAL] English:

[zend.git] / documentation / manual / zh / ref / coding_standard.xml

<appendix id="coding-standard">
  <title>Zend Framework 的 PHP 编码标准 </title>
    <sect1 id="coding-standard.overview">
        <title> 绪论 </title>

        <sect2 id="coding-standard.overview.scope">
            <title> 适用范围 </title>

            <para>
                本文档提供的代码格式和文档的指南是给参与 Zend Framework 的个人和团队使用的，许多使用 Zend Framework 的开发者
                也发现编码标准很有用，因为他们的代码风格和 Zend Framework 的代码保持一致。值得注意的是它要求切实努力来全面
                详细说明编码标准。

                注：有时候开发者认为在最详细的设计级别上标准的建立比标准所建议的更重要。Zend Framework 编码标准的指南
                实践上很好地工作于 ZF 项目。你可以根据我们的 <ulink url="http://framework.zend.com/license">license</ulink> 中的条款来修改或使用它们。
            </para>
            <para>
                ZF 编码标准的话题包括：

                <itemizedlist>
                    <listitem>
                        <para>PHP File 文件格式</para>
                    </listitem>

                    <listitem>
                        <para> 命名约定 </para>
                    </listitem>

                    <listitem>
                        <para> 编码风格 </para>
                    </listitem>

                    <listitem>
                        <para> 注释文档 </para>
                    </listitem>
                </itemizedlist>
            </para>
        </sect2>

        <sect2 id="coding-standard.overview.goals">
            <title> 目标 </title>

            <para>
                编码标准对任何开发项目都很重要，特别是很多开发者在同一项目上工作。编码标准帮助确保代码的高质量、少 bug 和容易维护。
            </para>
        </sect2>
    </sect1>

    <sect1 id="coding-standard.php-file-formatting">
        <title>PHP File 文件格式 </title>

        <sect2 id="coding-standard.php-file-formatting.general">
            <title> 常规 </title>

            <para>
                对于只包含有 PHP 代码的文件，结束标志（"?>"）是不允许存在的，PHP自身不需要（"?>"）, 这样做, 可以防止它的末尾的被意外地注入相应。
            </para>

            <para>
                <emphasis> 重要：</emphasis> 由 <code>__HALT_COMPILER()</code> 允许的任意的二进制代码的内容被 Zend Framework 中的 PHP 文件或由它们产生的文件禁止。
                这个功能的使用只对一些安装脚本开放。
            </para>
        </sect2>

        <sect2 id="coding-standard.php-file-formatting.indentation">
            <title> 缩进 </title>

            <para> 缩进由四个空格组成，禁止使用制表符 TAB 。</para>
        </sect2>

        <sect2 id="coding-standard.php-file-formatting.max-line-length">
            <title> 行的最大长度 </title>

            <para>
                一行 80 字符以内是比较合适，就是说，ZF 的开发者应当努力在可能的情况下保持每行代码少于 80 个字符，在有些情况下，长点也可以, 但最多为 120 个字符。
            </para>
        </sect2>

        <sect2 id="coding-standard.php-file-formatting.line-termination">
            <title> 行结束标志 </title>

            <para>
                行结束标志遵循 Unix 文本文件的约定，行必需以单个换行符（LF）结束。换行符在文件中表示为 10，或16进制的 0x0A。
            </para>

            <para>
                注：不要使用 苹果操作系统的回车（0x0D）或 Windows 电脑的回车换行组合如（0x0D,0x0A）。
            </para>
        </sect2>
    </sect1>

    <sect1 id="coding-standard.naming-conventions">
        <title> 命名约定 </title>

        <sect2 id="coding-standard.naming-conventions.classes">
            <title> 类 </title>

            <para>
                Zend Framework 的类命名总是对应于其所属文件的目录结构的，ZF 标准库的根目录是 “Zend/”，ZF 特别（extras）库的根目录是 "ZendX/"，所有 Zend Framework 的类在其下按等级存放。
            </para>

            <para>
                类名只允许有字母数字字符，在大部分情况下不鼓励使用数字。下划线只允许做路径分隔符；例如 Zend/Db/Table.php 文件里对应的类名称是 Zend_Db_Table。
            </para>

            <para>
                如果类名包含多个单词，每个单词的第一个字母必须大写，连续的大写是不允许的，例如 “Zend_PDF” 是不允许的，而 "Zend_Pdf" 是可接受的。
            </para>

            <para>
                这些约定为 Zend Framework 定义了一个伪命名空间机制。如果对开发者在他们的程序中切实可行，Zend Framework 将采用 PHP 命名空间特性（如果有的话）。
            </para>

            <para>
                参见在标准和特别库中类名作为类名约定的例子。

                <emphasis>重要：</emphasis> 依靠 ZF 库展开的代码，但又不是标准或特别库的一部分（例如程序代码或不是 Zend 发行的库），不要以 "Zend_" 或 "ZendX_" 开头。
            </para>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.filenames">
            <title> 文件名 </title>

            <para>
                对于其它文件，只有字母数字字符、下划线和短横线（"-"）可用，空格是绝对不允许的。
            </para>

            <para>
                包含任何 PHP 代码的任何文件应当以 ".php" 扩展名结尾，众所周知的视图脚本除外。下面这些例子给出 Zend Framework 类可接受的文件名：

                <programlisting role="php"><![CDATA[
Zend/Db.php

Zend/Controller/Front.php

Zend/View/Helper/FormRadio.php]]>
                </programlisting>

                文件名必须遵循上述的对应类名的规则。
            </para>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.functions-and-methods">
            <title> 函数和方法 </title>

            <para>
                函数名只包含字母数字字符，下划线是不允许的。数字是允许的但大多数情况下不鼓励。
            </para>

            <para>
                函数名总是以小写开头，当函数名包含多个单词，每个子的首字母必须大写，这就是所谓的 “驼峰” 格式。
            </para>

            <para>
                我们一般鼓励使用冗长的名字，函数名应当长到足以说明函数的意图和行为。
            </para>

            <para>
                这些是可接受的函数名的例子：

                <programlisting role="php"><![CDATA[
filterInput()

getElementById()

widgetFactory()]]>
                </programlisting>
            </para>

            <para>
                对于面向对象编程，实例或静态变量的访问器总是以 "get" 或 "set" 为前缀。在设计模式实现方面，如单态模式（singleton）或工厂模式（factory），
                方法的名字应当包含模式的名字，这样名字更能描述整个行为。
            </para>

            <para>
                在对象中的方法，声明为 "private" 或 "protected" 的， 名称的首字符必须是一个单个的下划线，这是唯一的下划线在方法名字中的用法。声明为 "public" 的从不包含下划线。
            </para>

            <para>
                全局函数 (如："floating functions") 允许但大多数情况下不鼓励，建议把这类函数封装到静态类里。

            </para>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.variables">
            <title> 变量 </title>

            <para>
                变量只包含数字字母字符，大多数情况下不鼓励使用数字，下划线不接受。
            </para>

            <para>
                声明为 "private" 或 "protected" 的实例变量名必须以一个单个下划线开头，这是唯一的下划线在程序中的用法，声明为 "public" 的不应当以下划线开头。
            </para>

            <para>
                对函数名（见上面 3.3 节）一样，变量名总以小写字母开头并遵循“驼峰式”命名约定。
            </para>

            <para>
                我们一般鼓励使用冗长的名字，这样容易理解代码，开发者知道把数据存到哪里。除非在小循环里，不鼓励使用简洁的名字如 "$i" 和 "$n" 。如果一个循环超过 20 行代码，索引的变量名必须有个具有描述意义的名字。
            </para>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.constants">
            <title> 常量 </title>

            <para>
                常量包含数字字母字符和下划线，数字允许作为常量名。
            </para>

            <para>
                常量名的所有字母必须大写。
            </para>

            <para>
                常量中的单词必须以下划线分隔，例如可以这样 <code>EMBED_SUPPRESS_EMBED_EXCEPTION</code> 但不许这样 <code>EMBED_SUPPRESSEMBEDEXCEPTION</code>。
            </para>

            <para>
                常量必须通过 "const" 定义为类的成员，强烈不鼓励使用 "define" 定义的全局常量。
            </para>
        </sect2>
    </sect1>

    <sect1 id="coding-standard.coding-style">
        <title> 编码风格 </title>

        <sect2 id="coding-standard.coding-style.php-code-demarcation">
            <title>PHP 代码划分（Demarcation）</title>

            <para>
                PHP 代码总是用完整的标准的 PHP 标签定界：

                <programlisting role="php"><![CDATA[<?php

?>]]></programlisting>
            </para>

            <para>
                短标签（ ）是不允许的，只包含 PHP 代码的文件，不要结束标签 （参见 <xref linkend="coding-standard.php-file-formatting.general" />）。
            </para>
        </sect2>

        <sect2 id="coding-standard.coding-style.strings">
            <title> 字符串 </title>

            <sect3 id="coding-standard.coding-style.strings.literals">
                <title> 字符串文字 </title>

                <para>
                    当字符串是文字(不包含变量)，应当用单引号（ apostrophe ）来括起来：

                    <programlisting role="php"><![CDATA[
$a = 'Example String';]]>
                    </programlisting>
                </para>
            </sect3>

            <sect3 id="coding-standard.coding-style.strings.literals-containing-apostrophes">
                <title> 包含单引号（'）的字符串文字 </title>

                <para>
                    当文字字符串包含单引号（apostrophe ）就用双引号括起来，特别在 SQL 语句中有用：

                    <programlisting role="php"><![CDATA[
$sql = "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'";]]>
                    </programlisting>

                    在转义单引号时，上述语法是首选的，因为很容易阅读。
                </para>
            </sect3>

            <sect3 id="coding-standard.coding-style.strings.variable-substitution">
                <title> 变量替换 </title>

                <para>
                    变量替换有下面这些形式：

                    <programlisting role="php"><![CDATA[
$greeting = "Hello $name, welcome back!";

$greeting = "Hello {$name}, welcome back!";]]>
                    </programlisting>
                </para>

                <para>
                    为保持一致，这个形式不允许：

                    <programlisting role="php"><![CDATA[
$greeting = "Hello ${name}, welcome back!";]]>
                    </programlisting>
                </para>
            </sect3>

            <sect3 id="coding-standard.coding-style.strings.string-concatenation">
                <title> 字符串连接 </title>

                <para>
                    字符串必需用 "." 操作符连接，在它的前后加上空格以提高可读性：

                    <programlisting role="php"><![CDATA[
$company = 'Zend' . ' ' . 'Technologies';]]>
                    </programlisting>
                </para>

                <para>
                    当用 "." 操作符连接字符串，鼓励把代码可以分成多个行，也是为提高可读性。在这些例子中，每个连续的行应当由 whitespace 来填补，例如 "." 和 "=" 对齐：

                    <programlisting role="php"><![CDATA[
$sql = "SELECT `id`, `name` FROM `people` "
     . "WHERE `name` = 'Susan' "
     . "ORDER BY `name` ASC ";]]>
                    </programlisting>
                </para>
            </sect3>
        </sect2>

        <sect2 id="coding-standard.coding-style.arrays">
            <title> 数组 </title>

            <sect3 id="coding-standard.coding-style.arrays.numerically-indexed">
                <title> 数字索引数组 </title>

                <para> 索引不能为负数 </para>

                <para>
                    建议数组索引从 0 开始。
                </para>

                <para>
                    当用 <code>array</code> 函数声明有索引的数组，在每个逗号的后面间隔空格以提高可读性：

                    <programlisting role="php"><![CDATA[
$sampleArray = array(1, 2, 3, 'Zend', 'Studio');]]>
                    </programlisting>
                </para>

                <para>
                    可以用 "array" 声明多行有索引的数组，在每个连续行的开头要用空格填补对齐：

                    <programlisting role="php"><![CDATA[
$sampleArray = array(1, 2, 3, 'Zend', 'Studio',
                     $a, $b, $c,
                     56.44, $d, 500);]]>
                    </programlisting>
                </para>
            </sect3>

            <sect3 id="coding-standard.coding-style.arrays.associative">
                <title> 关联数组 </title>

                <para>
                    当用声明关联数组，<code>array</code> 我们鼓励把代码分成多行，在每个连续行的开头用空格填补来对齐键和值：

                    <programlisting role="php"><![CDATA[
$sampleArray = array('firstKey'  => 'firstValue',
                     'secondKey' => 'secondValue');]]>
                    </programlisting>
                </para>
            </sect3>
        </sect2>

        <sect2 id="coding-standard.coding-style.classes">
            <title> 类 </title>

            <sect3 id="coding-standard.coding-style.classes.declaration">
                <title> 类的声明 </title>

                <para>
                    用 Zend Framework 的命名约定来命名类。
                </para><para>
                    花括号应当从类名下一行开始(the "one true brace" form)。
                </para><para>
                    每个类必须有一个符合 PHPDocumentor 标准的文档块。
                </para><para>
                    类中所有代码必需用四个空格的缩进。
                </para><para>
                    每个 PHP 文件中只有一个类。
                </para><para>
                    放另外的代码到类里允许但不鼓励。在这样的文件中，用两行空格来分隔类和其它代码。
                </para><para>
                    下面是个可接受的类的例子：
// 459 9506 － 441 9658 下次从这里开始
                    <programlisting role="php"><![CDATA[
/**
 * Documentation Block Here
 */
class SampleClass
{
    // 类的所有内容
    // 必需缩进四个空格
}]]>
                    </programlisting>
                </para>
            </sect3>

            <sect3 id="coding-standard.coding-style.classes.member-variables">
                <title> 类成员变量 </title>

                <para>
                    必须用Zend Framework的变量名约定来命名类成员变量。
                </para><para>
                    变量的声明必须在类的顶部，在方法的上方声明。
                </para><para>
                    不允许使用 <code>var</code> （因为 ZF 是基于 PHP 5 的 ），要用 <code>private</code>、 <code>protected</code> 或  <code>public</code>。
                    直接访问 public 变量是允许的但不鼓励，最好使用访问器 （set/get）。
                </para>
            </sect3>
        </sect2>

        <sect2 id="coding-standard.coding-style.functions-and-methods">
            <title> 函数和方法 </title>

            <sect3 id="coding-standard.coding-style.functions-and-methods.declaration">
                <title> 函数和方法声明 </title>

                <para>
                    必须用Zend Framework的函数名约定来命名函数。
                </para><para>
                    在类中的函数必须用 <code>private</code>、 <code>protected</code> 或 <code>public</code> 声明它们的可见性。
                </para><para>
                    象类一样，花括号从函数名的下一行开始(the "one true brace" form)。
                </para><para>
                    函数名和括参数的圆括号中间没有空格。
                </para>
                <para>
                    强烈反对使用全局函数。
                </para><para>
                    下面是可接受的在类中的函数声明的例子：

                    <programlisting role="php"><![CDATA[
/**
 * Documentation Block Here
 */
class Foo
{
    /**
     * Documentation Block Here
     */
    public function bar()
    {
        // 函数的所有内容
        // 必需缩进四个空格
    }
}]]>
                    </programlisting>
                </para>

                <para>
                    <emphasis>注：</emphasis> 传址（Pass-by-reference）是在方法声明中允许的唯一的参数传递机制。

                    <programlisting role="php"><![CDATA[
/**
 * Documentation Block Here
 */
class Foo
{
    /**
     * Documentation Block Here
     */
    public function bar(&$baz)
    {}
}]]>
                    </programlisting>
                </para>

                <para>
                    传址在调用时是严格禁止的。
                </para>


                <para>
                    返回值不能在圆括号中，这妨碍可读性而且如果将来方法被修改成传址方式，代码会有问题。

                    <programlisting role="php"><![CDATA[
/**
 * Documentation Block Here
 */
class Foo
{
    /**
     * WRONG
     */
    public function bar()
    {
        return($this->bar);
    }

    /**
     * RIGHT
     */
    public function bar()
    {
        return $this->bar;
    }
}]]>
                    </programlisting>
                </para>

            </sect3>

            <sect3 id="coding-standard.coding-style.functions-and-methods.usage">
                <title> 函数和方法的用法 </title>

                <para>
                    函数的参数应当用逗号和紧接着的空格分开，下面可接受的调用的例子中的函数带有三个参数：

                    <programlisting role="php"><![CDATA[
threeArguments(1, 2, 3);]]>
                    </programlisting>
                </para>

                <para>
                    传址方式在调用的时候是严格禁止的，参见函数的声明一节如何正确使用函数的传址方式。
                </para>
                <para>
                    带有数组参数的函数，函数的调用可包括 "array" 提示并可以分成多行来提高可读性，同时，书写数组的标准仍然适用：

                    <programlisting role="php"><![CDATA[
threeArguments(array(1, 2, 3), 2, 3);

threeArguments(array(1, 2, 3, 'Zend', 'Studio',
                     $a, $b, $c,
                     56.44, $d, 500), 2, 3);]]>
                    </programlisting>
                </para>
            </sect3>
        </sect2>

        <sect2 id="coding-standard.coding-style.control-statements">
            <title> 控制语句 </title>

            <sect3 id="coding-standard.coding-style.control-statements.if-else-elseif">
                <title>if/Else/Elseif</title>

                <para>
                    使用 <code>if</code> and <code>elseif</code> 的控制语句在条件语句的圆括号前后都必须有一个空格。
                </para>

                <para>
                    在圆括号里的条件语句，操作符必须用空格分开，鼓励使用多重圆括号以提高在复杂的条件中划分逻辑组合。
                </para>

                <para>
                    前花括号必须和条件语句在同一行，后花括号单独在最后一行，其中的内容用四个空格缩进。

                    <programlisting role="php"><![CDATA[
if ($a != 2) {
    $a = 2;
}]]>
                    </programlisting>
                </para>

                <para>
                      对包括"elseif" 或 "else"的 "if" 语句，和 "if" 结构的格式类似，
                      下面的例子示例 "if" 语句， 包括 "elseif" 或 "else" 的格式约定：

                    <programlisting role="php"><![CDATA[
if ($a != 2) {
    $a = 2;
} else {
    $a = 7;
}


if ($a != 2) {
    $a = 2;
} elseif ($a == 3) {
    $a = 4;
} else {
    $a = 7;
}]]>
                    </programlisting>
                    在有些情况下， PHP 允许这些语句不用花括号，但在(ZF) 代码标准里，它们（"if"、 "elseif" 或 "else" 语句）必须使用花括号。
                </para>

                <para>
                    "elseif" 是允许的但强烈不鼓励，我们支持 "else if" 组合。
                </para>
            </sect3>

            <sect3 id="coding-standards.coding-style.control-statements.switch">
                <title>Switch</title>

                <para>
                    在 "switch" 结构里的控制语句在条件语句的圆括号前后必须都有一个单个的空格。
                </para>

                <para>
                    "switch" 里的代码必须有四个空格缩进，在"case"里的代码再缩进四个空格。
                </para>

                <programlisting role="php"><![CDATA[
switch ($numPeople) {
    case 1:
        break;

    case 2:
        break;

    default:
        break;
}]]>
                </programlisting>

                <para>
                    <code>switch</code> 语句应当有 <code>default</code>。
                </para>

                <para>
                    <emphasis>注：</emphasis> 有时候，在 falls through 到下个 case 的 <code>case</code> 语句中不写 <code>break</code> or <code>return</code> 很有用。
                    为了区别于 bug，任何 <code>case</code> 语句中，所有不写 <code>break</code> or <code>return</code> 的地方应当有一个 "// break intentionally omitted" 这样的注释来表明 break 是故意忽略的。
                </para>
            </sect3>
        </sect2>

        <sect2 id="coding-standards.inline-documentation">
            <title> 注释文档 </title>

            <sect3 id="coding-standards.inline-documentation.documentation-format">
                <title> 格式 </title>

                <para>
                    所有文档块 ("docblocks") 必须和 phpDocumentor 格式兼容，phpDocumentor 格式的描述超出了本文档的范围，关于它的详情，参考：<ulink url="http://phpdoc.org/">http://phpdoc.org/</ulink>。
                </para>

                <para>
                    所有类文件必须在文件的顶部包含文件级 （"file-level"）的 docblock ，在每个类的顶部放置一个 "class-level" 的 docblock。下面是一些例子：
                </para>
            </sect3>

            <sect3 id="coding-standards.inline-documentation.files">
                <title> 文件 </title>

                <para>
                    每个包含 PHP 代码的文件必须至少在文件顶部的 docblock 包含这些 phpDocumentor 标签：

                    <programlisting role="php"><![CDATA[
/**
 * 文件的简短描述
 *
 * 文件的详细描述（如果有的话）... ...
 *
 * LICENSE: 一些 license 信息
 *
 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/3_0.txt   BSD License
 * @version    $Id:$
 * @link       http://framework.zend.com/package/PackageName
 * @since      File available since Release 1.5.0
*/]]>
                    </programlisting>
                </para>
            </sect3>

            <sect3 id="coding-standards.inline-documentation.classes">
                <title> 类 </title>

                <para>
                    每个类必须至少包含这些 phpDocumentor 标签：

                    <programlisting role="php"><![CDATA[
/**
 * 类的简述
 *
 * 类的详细描述 （如果有的话）... ...
 *
 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/   BSD License
 * @version    Release: @package_version@
 * @link       http://framework.zend.com/package/PackageName
 * @since      Class available since Release 1.5.0
 * @deprecated Class deprecated in Release 2.0.0
 */]]>
                    </programlisting>
                </para>
            </sect3>

            <sect3 id="coding-standards.inline-documentation.functions">
                <title> 函数 </title>

                <para>
                    每个函数，包括对象方法，必须有最少包含下列内容的文档块（docblock）：

                    <itemizedlist>
                        <listitem><para> 函数的描述 </para></listitem>
                        <listitem><para> 所有参数 </para></listitem>
                        <listitem><para> 所有可能的返回值 </para></listitem>
                    </itemizedlist>
                </para>

                <para>
                    因为访问级已经通过 "public"、 "private" 或 "protected" 声明， 不需要使用 "@access"。
                </para>

                <para>
                    如果函数/方法抛出一个异常，使用 @throws 于所有已知的异常类：

                    <programlisting role="php"><![CDATA[
@throws exceptionclass [description]]]>
                    </programlisting>
                </para>
            </sect3>
        </sect2>
    </sect1>

</appendix>
<!--
vim:se ts=4 sw=4 et:
-->