Zend Framework 中的 Php 编码标准 (三) - 编码风格

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

Zend Framework 中的 Php 编码标准 (三) - 编码风格

1. PHP 代码必须以完整的形式来定界，短定界符只能用在视图。

例如 ：


<?php

// Php code here

?>

   

// index.phtml

<?=  'hello'  ?>



复制代码

2. 当一个字符串是纯文字组成的时候（即不含有变量），则必须总是以单引号（'）或者撇号（`）作为定界符。

例如 ：

$a  =  'Example String' ;

$b  = ` Excute Something `;

复制代码

3. 当一个字符串含有撇号（`）的时候，我们允许使用双引号（"）来定界字符串，特别是在些 SQL 语句的时候。

例如 ：

$sql  =  "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'" ;

复制代码

4. 变量替换中的变量只允许用 $+变量名 的形式。

例如 ：

$greeting  =  "Hello $name, welcome back!" ;    // 允许

$greeting  =  "Hello {$name}, welcome back!" ;  // 允许

$greeting  =  "Hello ${name}, welcome back!" ;  // 不允许

复制代码

5. 多个字符串必须用点号 "." 来连接，且字符串与点号间必须用一个空格隔开。

例如 ：

$company  =  'Zend'  .  'Technologies' ;

复制代码

6. 当用点号 "." 连接各字符串的时候，我们允许把它分割成多行以增强可读性。在这种情况下，点号 "." 必须与等于号 "=" 对齐。

例如 ：

$sql  =  "SELECT `id`, `name` FROM `people` "

      .  "WHERE `name` = 'Susan' "

      .  "ORDER BY `name` ASC " ;

复制代码

7. 任何负数都不允许作为数组的索引，数组索引必须以任何非负数作为开头，而且强烈建议以0作为默认开头。

例如 ：

$sampleArray  = array(- 1  => - 1 ,  0  =>  0 );  // 错误

$sampleArray  = array( 0  => - 1 ,  1  =>  0 );   // 正确

$sampleArray  = array( 1  => - 1 ,  2  =>  0 );   // 正确

复制代码

8. 当用 array 类型符号来构造数组的时候，必须在每个逗号之后加上一个空格来增强可读性。

例如 ：

$sampleArray  = array( 1 ,  2 ,  3 ,  'Zend' ,  'Studio' );

复制代码

9. 多行的索引数组同样允许用 array 类型符号来构造，只是我们需要为每行的每个值加上必要的空格来保持其整齐美观。

例如 ：

$sampleArray  = array( 1 ,         2 ,   3 ,   'Zend' ,

                      'Studio' ,  $a ,  $b ,  $c ,

                      56.44 ,     $d ,  500 );

复制代码

10. 当使用 array 类型符声明关联数组的时候，我们鼓励把它分成多个行，只是我们必须同时保证每行的键与值的对齐，以保持美观。

例如 ：

$sampleArray  = array( 'firstKey'   =>  'firstValue' ,

                      'secondKey'  =>  'secondValue' );

复制代码

11. 中括号的开始必须在类名的下一行顶格。

例如 ：

class  foo

{

     // 正确 {} 写法

}

class  foo  {

     // 错误 {} 写法

}

复制代码

12. 类定义必须拥有符合 phpDocumentor 标准的注释块。

例如 ：

/**

 * 类定义注释

 */

class  Zend_Class

{

}

复制代码

13. 类中的所有代码都必须用4个空格来进行缩进。

例如 ：

class  Zend_Class

{

     $spaces  =  '4 spaces' ;

    if ( $spaces  ==  '4 spaces' ) {

        echo  'is permitted !' ;

    }

}

class  Zend_Class

{

   $spaces  =  'less then 4 spaces' ;

  if ( $spaces  !=  '4 spaces' ) {

    echo  'is not permitted !' ;

  }

}

复制代码

14. 每个 php 文件只允许声明一个类。在类文件里面写其它代码是允许的，但并不鼓励这样做。假如真要附加代码的话，必须用空行来分隔。

例如 ：


<?php

// 允许但并不鼓励这样做

class  Zend_Class

{

    static  $foo  =  'foo' ;

}

echo  Zend_Class :: $foo ;



<? php

/**

 * 在同一文件里声明超过两个类是不允许的

 */

class  Class_One

{

}

class  Class_Two

{

}

?>



复制代码

15. 任何类变量的声明都必须放在类顶部，先于任何函数的声明。

例如 ：

// 正确

class  right

{

    public  $foo  =  '先于函数定义' ;

    public function  fun ()

    {

    }

}

// 错误

class  wrong

{

    public function  fun ()

    {

    }

    public  $foo  =  '后于函数定义' ;

}

复制代码

16. 不允许用 var 符号来声明变量，类成员变量必须以 private，protected 和 public 来声明。其次，把类成员声明为 public 而直接引用虽然是允许的，但通常更好的方法是使用 get 和 set 方法来访问类成员。

例如 ：

class  foo

{

    var  $unpermitted  =  '这是不允许的!' ;

    private  $privateVariable  =  '私有变量' ;

    protected  $protectedVariable  =  '保护变量' ;

    public  $publicVariable  =  '公共变量' ;

    public function  setPrivateVariable ( $value )

    {

         $this -> privateVariable  =  $value ;

    }

    public function  getPrivateVariable ()

    (

        return  $this -> privateVariable ;

    )

}

$foo  = new  foo ();

// 不鼓励使用

echo  $foo -> publicVariable ;

// 鼓励使用

echo  $foo -> getPrivateVariable ();

复制代码

17. 方法和函数必须总是用 private，protected 或者 public 来声明其作用域。

例如 ：

class  foo

{

    function  goo ()

    {

         // 不允许的

     }

    private function  bar ()

    {

         // 正确

     }

    protected function  baz ()

    {

         // 正确

     }

    public function  zoo ()

    {

         // 正确

     }

}

复制代码

18. 按照 php 社区的习惯，静态 static 方法应该声明其作用域。

例如 ：

class  foo

{

    static function  baz ()

    {

         // 不允许的

     }

    public static function  bar ()

    {

         // 正确

     }

}

复制代码

19. 对于类成员函数和方法，中括号的开始必须位于函数和方法名的下一行顶格。

例如 ：

class  foo

{

    public function  braceIsUnderneath ()

    {

         // 正确

     }

    public function  braceIsNotUnderneath () {

         // 错误

     }

}

复制代码

20. 在函数名与参数括号之间不允许出现多余的空格。

例如 ：

class  foo

{

    public function  someSpacesAfterMe   ( $a )

    {

         // 错误

     }

    public function  noSpacesAfterMe ( $a )

    {

         // 正确

     }

}

复制代码

21. 引用只允许定义在函数参数中，实时传递引用是禁止的。

例如 ：

function  defineRefInMethod (& $a )

{

     $a  =  'a' ;

}

function  callTimePassRef ( $a )

{

     $a  =  'a' ;

}

$b  =  'b' ;

$c  =  'c' ;

// 允许的

defineRefInMethod ( $b );

echo  $b ;  // 'a'

// 禁止的

callTimePassRef (& $c );

echo  $c ;  // 'a'

复制代码

22. 函数返回值不可以用括号包住，不然会降低可读性，而且假如以后函数修改为返回引用的话，这将会抛出一个异常。

例如 ：

class  foo

{

    public  $bar  =  'bar' ;

    public function  goo ()

    {

        return ( $this -> bar );

    }

    public function &  zoo ()

    {

        return ( $this -> bar );

    }

}

$foo  = new  foo ();

// 看起来没问题

echo  $foo -> goo ();

/**

 * 程序会抛出一个 notice 说 :

 * "Only variable references should be returned by reference"

 */

echo  $foo -> zoo ();

复制代码

23. 鼓励尽量使用类型提示，特别是在模块设计中。

例如 ：

class  Zend_Component

{

    public function  foo ( SomeInterface $object )

    {}

 

    public function  bar (array  $options )

    {}

}

复制代码

24. 尽量避免同时使用异常处理和类型提示，来检验参数的有效性。

例如 ：

class  Not_Zend_Class

{

}

class  foo

{

    public function  bar ( Zend_Class $zc )

    {

    }

    public function  goo ( $zc )

    {

        if (! $zc  instanceof  Zend_Class ) {

            throw new  Exception ( '$zc 不是 Zend_Class 的实例' );

        }

    }

}

$foo  = new  foo ();

$zc   = new  Not_Zend_Class ();

/**

 * Catchable fatal error 错误显示 :

 * "Argument 1 passed to foo::bar() must be an instance of Zend_Class,

 * instance of Not_Zend_Class given"

 */

$foo -> bar ( $zc );

/**

 * 错误信息 : '$zc 不是 Zend_Class 的实例'

 */

try {

     $foo -> goo ( $zc );

} catch ( Exception $e ) {

    echo  $e -> getMessage ();

}

复制代码

25. 函数参数必须用 逗号+空格 来分隔。

例如 ：

// 正确

threeArguments ( 1 ,  2 ,  3 );

// 错误

threeArguments ( 1 , 2 , 3 );

复制代码

26. 对于参数为数组的函数，参数中的数组应该分成多行以增强可读性。

例如 ：

threeArguments (array( 1 ,  2 ,  3 ),  2 ,  3 );

threeArguments (array( 1 ,         2 ,   3 ,     'Zend' ,

                      'Studio' ,  $a ,  $b ,    $c ,

                      56.44 ,     $d ,  500 ),  2 ,       3 );

复制代码

27. 基于 “if”, "else" 和 "else if" 的条件控制里，我们必须用空格间隔开语句和括号。

例如 ：

// 正确

if ( $spaceOutSide ) {

     // ...

} else if ( $spaceOutSide ) {

     // ...

} else {

     // ...

}

// 错误

if( $noSpaceOutSide ){

     // ...

}else if( $noSpaceOutSide ){

     // ...

}else{

     // ...

}

复制代码

28. 在条件控制语句的条件括号内，必须用空格将操作符与其它元素隔开。如果遇到很长的逻辑判断，则鼓励用内嵌括号来分割各个逻辑。

例如 ：

if (( $a  !=  2 ) and ( $b  ==  1 )) {

     $a  =  $b ;

}

复制代码

29. 中括号的开始 "{" 必须与条件控制语句位于同一行，结束 "}" 必须总是独占一行且顶格，控制流程内容必须用4个空格进行缩进。

例如 ：

// 正确

if ( $braceSameLine ) {

    echo  '很好 : 4空格缩进' ;

}

// 错误

if ( $braceNotSameLine )

{

  echo  '不好 ： 2空格缩进' ;

}

复制代码

30. 在某些场合，php 允许条件控制语句舍弃中括号 "{}" ，但是根据此编码规范，所有 "if", "else if" 或 "else" 语句都必须使用中括号 "{}" 定界内容。

例如 ：

// 用 "{}" 定界内容是正确的

if ( $a  !=  2 ) {

     $a  =  2 ;

} else if ( $a  ==  3 ) {

     $a  =  4 ;

} else {

     $a  =  7 ;

}

// 没有用 "{}" 定界是错误的

if ( $a  !=  2 )

     $a  =  2 ;

else if ( $a  ==  3 )

     $a  =  4 ;

else

     $a  =  7 ;

复制代码

31. "elseif" 语句是不允许的，必须使用 "else if" 。

例如 ：

if ( true ) {

     //

} else if {

     // 正确

}

if ( true ) {

     //

} elseif {

     // 错误

}

复制代码

32. "switch" 条件控制语句中，必须用空格将待测参数与其它元素分隔开。

例如 ：

switch ( $num ) {

     // 正确

}

switch( $num ){

     // 错误

}

复制代码

33. "switch" 语句的内容必须以4个空格缩进，"case" 条件控制的内容必须再加4个空格进行缩进。

例如 ：

switch ( $indentedSpaces ) {

  case  2 :

    echo  "错误" ;

    break;

    case  4 :

        echo  "正确" ;

        break;

    default:

        break;

}

复制代码

34.在 "switch" 语句中应该总是包括 "default" 控制。

例如 ：

switch ( $isWithDefault ) {

    case  false :

        break;

    default:

        echo  "有 'default' 控制是正确的" ;

        break;

}

switch ( $isWithDefault ) {

    case  false :

        echo  "没有 'default' 控制是错误的" ;

        break;

}

复制代码

35. 有时候我们需要在 "case" 语境中省略掉 "break" 或 "return" ，这个时候我们必须为这些 "case" 语句加上 "// break intentionally omitted" 注释。

例如 ：

switch ( $numPeople ) {

    case  1 :  // break intentionally omitted

     case  2 :

        break;

    default:

        break;

}

复制代码

36. 关键词 "global" 是不允许使用的，请用 $GLOBAL[xxx] 替代。

例如 ：

$a  =  'a' ;

function  foo ()

{

     // 错误

     global  $a ;

     $foo  =  $a ;

     // 正确

     $foo  =  $GLOBALS [ 'a' ];

    return  $foo ;

}

echo  foo ();

复制代码

.