Protoss/规范/代码规范

写在前面： 本规则基于PEAR的代码书写规范，但是又有些许改进，在不同的地方会指出。

缩进规则与行书写规范

所有代码中，均使用4个空格作为缩进标准，不允许使用制表符(tab)。
这样做的好处是：不管什么系统或者编辑器下看，代码都是整齐的。在使用SVN、CVS等工具或者查看diff时，不会对编码和阅读人员带来困难。

如果你使用的是的Emacs编辑器，请设置“indent-tabs-mode”。
如果你使用的是大蛇所钟爱的Vim(GVim)的话，请在_vimrc中作如下设置：
set expandtab
set shiftwidth=4
set softtabstop=4
set tabstop=4

所有的[运算符(包括算术运算符、赋值运算符、位运算符、比较运算符等等)]的左边和右边都需要有一个空格。

控制结构书写规范

Control Structures，多译作控制结构，可以参考[PHP手册]。
其实说白了就是if, for, while, switch这些啦。

条件简单时

<?php
 
if ((condition1) || (condition2)) {
    action1;
} elseif ((condition3) && (condition4)) {
    action2;
} else {
    defaultaction;
}

注意上面这段代码中，if与“(”之间有个空格，两个条件与符号间有空格。“)”与“{”之间有空格，并且是在同一行。
else和elseif的前后大括号“}”和“{”都在同一行。

如果是switch的话，写成这样：

<?php
 
switch (condition) {
case 1:
    action1;
    break;
 
case 2:
    action2;
    break;
 
default:
    defaultaction;
    break;
}

注意case和switch的缩进级别是一致的。

条件复杂时

这种写法可以强调第一个条件，同时也属于中规中矩的写法。

<?php
 
if (($condition1
    || $condition2)
    && $condition3
    && $condition4
) {
    //code here
}

下面这种写法是将多个条件对齐。好处显而易见，这样可以方便的一眼扫完所有条件，而且结构清晰。

<?php
 
if (   $condition1
    || $condition2
    || $condition3
) {
    //code here
}

<?php
 
$is_foo = ($condition1 || $condition2);
$is_bar = ($condition3 && $condtion4);
if ($is_foo && $is_bar) {
    // ....
}

三元运算符

<?php
 
$a = $condition1 && $condition2
    ? $foo : $bar;
 
$b = $condition3 && $condition4
    ? $foo_man_this_is_too_long_what_should_i_do
    : $bar;

函数调用的书写规范

单行调用函数

函数调用时，函数名与“(”之间不能有空格；中间的第个参数与其之前的参数后的“,”之间要有一个空格，但是参数自己后面的“,”之间不能有空格；最后一个参数与“)”之间不能有空格。

<?php
$var = foo($bar, $baz, $quux);

如上面的代码所表述的，“=”的两边都需要有空格，但是如果情况特殊，上下文中都是类似的函数调用操作时，应当以“=”为参照物来对齐，如下：

<?php
$short         = foo($bar);
$long_variable = foo($baz);

为了增加可读性，我们也可以在函数/类的方法调用时，写成这样：

<?php
 
$this->callSomeFunction('param1',     'second',        true);
$this->callSomeFunction('parameter2', 'third',         false);
$this->callSomeFunction('3',          'verrrrrrylong', true);

多行书写格式

当一行书写超过80个字节的时候，请分开成多行来书写，如下：

<?php
 
$this->someObject->subObject->callThisFunctionWithALongName(
    $parameterOne, $parameterTwo,
    $aVeryLongParameterThree
);

因为不是每个人都有很宽的显示器的，一般来说，如果看代码需要横向滚屏的话，会很不爽，因此需要分多行书写。为了方便阅读，一些很长的变量名(所以大蛇不建议你用很长的变量名)最好另起一行，同时几个参数写在同一行也是允许的，但是相对所属的调用函数这一级前面要加4个空格的缩进。
另外，要记得行末的“,”要跟着它前面的参数，且中间不能有空格。
好了，让我们来看一个变态点的：

<?php
 
$this->someObject->subObject->callThisFunctionWithALongName(
    $this->someOtherFunc(
        $this->someEvenOtherFunc(
            'Help me!',
            array(
                'foo'  => 'bar',
                'spam' => 'eggs',
            ),
            23
        ),
        $this->someEvenOtherFunc()
    ),
    $this->wowowowowow(12)
);

并不是说一行满了的情况下才需要换行，很多时候为了增加代码的可读性，我们也用换行来书写，就像上面这段这样。还是老话，注意层级关系。

连贯查询是个不错的东西，但是同样也会造成一条语句很长，所以我们也分行来书写，规则是在每个箭头“->”的位置换行，前面同样的是4个空格。

<?php
 
$condition = array(
    $someModel->primaryKey       => 123,
    'some_other_conditions_here' => 'blabla'
);
$someModel->select()
    ->where($condition)
    ->orderby('created DESC');
    ->execute()
    ->fetch();

上下文对齐标准

一般情况，我们这样对齐：

<?php
 
$short  = foo($bar);
$longer = foo($baz);

当上下文的两行代码的变量名都差不多长时，应当以“=”为参照物来对齐，“=”的两边都需要有空格。
但是如果碰到一变量名短的变态，一个长得变态时，应该不去对齐。

<?php
 
$short = foo($bar);
$thisVariableNameIsVeeeeeeeeeeryLong = foo($baz);

过长的语句要分行

 
<?php
$rows[$otherrow->something]->somemethod->returnArray
    =  $this->xajax->getJavascript(t3lib_extMgm::siteRelPath('nr_xajax'));

定义类的书写规范

类名后的大括号“{”要换行顶格书写。 <source_lang="php"> <?php class Foo_Bar {

   //... code goes here

} </source>

NOTICE

本节以下内容为非PEAR的书写规范，但是却是很多年经验的总结，这些经验一部分来自己我自己，另一部分也是“道上”的优秀习惯。

类的命名使用aaa_bbb这样的方法时，应当以“_”为分割符，后段为前段包内的子项，他们是上下级关系。
更多更详细介绍请参考：Protoss中的类命名规范。

定义函数的书写规范

标准函数定义书写规范

函数的定义基于K&R标准。 <source_lang="php"> <?php function fooFunction($arg1, $arg2 = ) {

   if (condition) {
       statement;
   }
   return $val;

} </source> 引申：
Brian W．Kernighan(柯尼汉)和Dennis M．Ritchie(里奇)合著了影响深远的名著《The C Programming Language》，常常称它为‘K&R’。 带默认值的参数应当写的参数列表的最后几个。通常都要返回有意义的值。下面来看个长点的例子： <source_lang="php"> <?php function connect(&$dsn, $persistent = false) {

   if (is_array($dsn)) {
       $dsninfo = &$dsn;
   } else {
       $dsninfo = DB::parseDSN($dsn);
   }

   if (!$dsninfo || !$dsninfo['phptype']) {
       return $this->raiseError();
   }

   return true;

} </source>

多行函数定义书写规范

老规矩，每行最多80个字符。超过的话，就要换行。注意几点：

• 换行后的参数前要有4个空格
• “)”应该和关键字“function”对齐
• “)”和“{”之间要有1个空格

<source_lang="php"> <?php

function someFunctionWithAVeryLongName($firstParameter = 'something', $secondParameter = 'booooo',

   $third = null, $fourthParameter = false, $fifthParameter = 123.12,
   $sixthParam = true

) {

   //....

} </source>

数组的书写规范

<source_lang="php"> <?php

$some_array = array(

   'foo'  => 'bar',
   'spam' => 'ham',

); </source> 数组中的对齐参照物为“=>”，符号左边至少要保证1个空格，而右边也需要1个空格。