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