Zend Framework 中的 Php 编码标准 (二) - 命名约定

原文 ：  http://kbs.kimbs.cn/blog/list/post/24/title/zend-framework-coding-standards-for-php-naming-conventions

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 ();

    }

    ......

}

复制代码

.