zend framework 中的 php 编码标准 (二) - 命名约定...

1. 类命名总是对应于其所属文件的目录结构。

这源于 PEAR 命名约定，能让人从类名就能联想到该类的存放位置。

例如 ：
Zend_Acl_Role 就代表 Zend/Acl/Role.php 文件。 
  


require_once 'Zend/Acl/Role/Interface.php';
class Zend_Acl_Role implements Zend_Acl_Role_Interface
{
    ......
}


这是规定实际上提供了一种伪命名空间机制，这在 php5.3 和 php6 里面都将得到支持，到时候 Zend Framework 可能会有一翻变革。


2. 类名只允许有字母和数字字符，在大部分情况下不鼓励使用数字。下划线只允许做路径分隔符。

这也源自 PEAR 命名约定，只不过 Zend Framework 在其基础上制定了更严格的规定。

例如 ：
Zend_Db_Table 是允许的。
Zend_Db_Table2 则是不鼓励的。
Zend-Db-Table 是不允许的。


3. 当你为其他开发人员提供 API 接口的时候，如果他们需要用一个复合的名称来确认这个接口，那么你必须把这个名称用下滑线 (underline) 隔开，而不是使用驼峰的形式。而且最好是以常量 (contant) 的形式。

这个规定可能有点难懂，让我们举个例子吧。例如在实例化 Zend_Db_Adapter_xxx 实例时，我们通常需要将 adapter 的名称作为参数传入到 Zend_Db::factory() 并由该工厂返回所需实例。

我们可以实例化 MySQL PDO 驱动 ：

$db = Zend_Db::factory('PDO_MYSQL', $config);


也可以实例化 MsSQL PDO 驱动 ：

$db = Zend_Db::factory('PDO_MSSQL', $config);



4. 如果类名包含多个单词，每个单词的第一个字母必须大写，连续的大写是不允许的。

例如 ：
Zend_PDF 是不允许的。
Zend_Pdf 才是标准写法。


5. 有 Zend 及其合作伙伴开发的 Zend Framework 类的命名必须总是以 "Zend_" 作为开头，并放在 "Zend/" 目录下。

例如 ：
Zend_Db 是由 Zend 开发的，它通常以 “Zend/Db.php” 的形式存放。
My_Db 则是用户自己定义或继承自 Zend_Db 的类，所以它不得以 "Zend_" 作为开头，而且通常以 "My/Db.php" 的形式存放。


6. 接口类 (interface) 的定义必须遵循类名的定义规范，不同的是必须要以 _Interface 作为结尾。

例如 ：
Zend_Controller_Dispatcher_Interface 对应的是 Zend/Controller/Dispatcher/Interface.php
 


7. 对于文件名，只有字母、数字字符、下划线和短横线 ("-") 可用，空格是绝对不允许的。

例如 ：
Zend/Controller/Front.php 是标准写法。
My/Controller/Common-Action_2.php 也是允许的。
My/Controller/Common Action.php 则是禁止的。


8. 包含任何 PHP 代码的任何文件应当以 ".php" 扩展名结尾，视图脚本默认拓展名是 ".phtml"，也可以用 ".html" 等代替。

例如 ：
Zend/Controller/Front.php 是标准 php 文件写法，index.phtml 是默认视图脚本名。

我相信很多人都见过以下的一些 php 的拓展名 ：
.php4
.php5
.phpx
.class.php
.include.php
html (开玩笑？)

而在 Zend Framework 中你只会见到一种，那就是 ".php"。


9. 函数名只允许由数字或字母组成，下划线是不允许的，首字母要小写，其后每个单词首字母要大写，即所谓的 “camelCaps” 规则。

例如 ：

filterInput()
getElementById()
widgetFactory()


等都是规范的写法。

而 ：

FilterInput3()
getelementbyid()
widget_factory()


等都是不允许的。


10. 函数名越详细越好，应该能够描述清楚该函数的功能。

例如 ：

getOne($id) // 描述的不清不楚。
getOneRecordById($id) // 则非常详细而清晰。



11. 对于对象成员的访问，我们必须始终使用 “get” 和 “set” 方法。

例如 ：

class Foo
{
    protected $_testObj;

    public function getTestObj()
    {
        return $this->_testObj;
    }

    public function setTestObj($testObj)
    {
        $this->_testObj = $testObj;
    }
}



12. 当我们使用了某些设计模式的时候，我们的方法中应该含有该模式名。

例如 ：

abstract class Zend_Cache
{
    // ......

    public static function factory($frontend, $backend,
        $frontendOptions = array(), $backendOptions = array(), 
        $customFrontendNaming = false, $customBackendNaming = false, 
        $autoload = false)
    {
        // ......
    }
}



13. 当类成员函数被声明为 private 或者 protected 时，函数必须以下划线 "_" 为开头，一般情况下的函数不含下划线。

例如 ：

class Zend_Foo
{
    protected function _fooBar()
    {
        // ...
    }
}



14. 如果我们需要把一些经常使用的函数或方法定义为全局函数，那么应该把它们以静态 (static) 的形式定义在类中。

例如 ：

class Zend_Debug
{
    // ......

    public static function dump($var, $label = null, $echo = true)
    {
        // ......
    }
}



15. 在类中被声明为 static 的函数或变量不应该再被声明为 private 私有，而应该为 protected 或者public ，如果只是不想被子类继承，则应该用 final 声明它们。

例如 ：

class Foo
{
    final public static function fooFinally()
    {
    }
}

class Bar extends Foo
{
}

// This is wrong
Bar::fooFinally();

// Use Foo::fooFinally() instead
Foo::fooFinally();



16. 函数或方法的初始中括号应该在函数声明的下一行顶格。

例如 ：

function Myfunction($parameter1)
{
}



17. 当函数参数不一定需要被赋值的时候，用 "null" 来代替 "false" 作为函数参数的默认值，除非该参数是 boolean 值。

例如，考虑如下代码 ：

public function foo($required, $optional = null)
{
    if (isset($optional)) {
        echo 'Echo something only when $optional is set and != null';
    }
}

public function foo($required, $optional = false)
{
    if (isset($optional)) {
        echo 'Always echo something';
    }
}



18. 变量只允许由字母组成，数字或下划线都是不允许的。

例如 ：

$foo // 是正确的
$foo_foo // 是错误的
$foo2 // 也是错误的



19. 被声明为 private 或者 protected 的类成员属性必须由下划线 "_" 作为开头，这也是唯一一种允许变量中出现下划线的情况，而声明为 public 的成员属性则在任何时候都不允许含有下划线。

例如 ：

class Zend_Foo
{
    private $_barPrivate;
    protected $_barProtected;
    public $barPublic;
}



20. 变量名必须像函数名那样，即首字母要小写，其后每个单词首字母要大写，即所谓的 “camelCaps” 规则。

例如 ：

$compatibilityMode
$registryClassName



21. 建议用描述性的变量的命名，变量名越详细越好，以至于像 $i 或 $n 等等都是不鼓励使用的，特别是在超过20行的循环里面。

例如 Zend_Search_Lucene 中的一段代码 ：

// read segmentInfos
for ($count = 0; $count < $segments; $count++) {
    $segName = $segmentsFile->readString();
    ......
}



22. 常量 constant 必须仅包括字母，数字和下划线，而且必须全部大写，各个单词之间用下划线分割。

例如 ：

"MY_CONSTANT_ONE" // 是允许的
"MYCONSTANTTWO" // 是不允许的
"my_constant_two" // 也是不允许的



23. 常量应该在类中由 const 声明并定义，全局范围内的 define 是不鼓励使用的。

例如 ：

class Zend_Acl
{
    const TYPE_ALLOW = 'TYPE_ALLOW';
    const TYPE_DENY  = 'TYPE_DENY';
    ......
}



24. 和 php 文档说明不一样的是，Zend Framework 中的 boolean 值和 null 值都是用小写的。

例如 Zend_Mail 中的一段代码 ：

public function setMessageId($id = true)
{
    if ($id === null || $id === false) {
        return $this;
    } elseif ($id === true) {
        $id = $this->createMessageId();
    }
    ......
}