澳门新葡萄京官网首页phpBB 编码标准规范

以前发过,今天又校对了一下,也当是自己又重新温习了一遍,又有新的感觉。不愧是久负盛名的开源项目,编码规范简单精练,切中要害。希望能对大家有所帮助,欢迎交流看法。
phpBB 编码标准规范如果您对原手册内容有注解或建议,请发电子邮件至
nate@phpbb.com
;如果您对本文翻译有什么意见或建议,请联系QQ78045595,或发电子邮件至gaogan
at gmail dot com.编辑器设定制表符 vs
空格:为了此事尽可能地简单,我们使用制表符,不用空格。
你可以随便设定编辑器使用多少空格显示制表符,但是必须保证当你保存文件时,它保存的是制表符而不是空格。
这样,我们每个人都可以让代码以我们喜欢的方式显示,同时不破坏实际文件的布局。
换行: 确保编辑器将文件保存为 Unix
格式。这意味着以换行符终止一行,而不是在 Win32 里那样用一个 CR/LF
对,也不是 Mac 所用的某种方式。任何规范的 Win32
编辑器应该做到这点,但这并不见得总是默认的。你需要熟悉你的编辑器。如果你需要有关使用
Windows 文本编辑器的建议,应该去咨询它的开发者。他们中有些人在 Win32
中做编辑工作。命名约定在我们的命名约定中,不会使用任何形式的匈牙利命名。我们很多人相信,匈牙利命名是导致代码混乱的一种主要手法。变量名称:变量名应当全部小写,并且词语之间以单个下划线分隔。
例如: $current_user 是正确的, 但是 $currentuser 和 $currentUser
就不正确。名称应当是描述性的,并且简明。我们自然不希望使用冗长的句子作为变量名,但是多输入几个字符总好于疑惑于某个变量到底是干什么用的。
循环计数器:允许使用一个单字符变量名的唯一情形是当它作为一个循环计数器的时候。在这种情况下,外层循环的计数器应当始终是
$i。如果有一个循环处于这个循环的内部,它的计数器应当是 $j,进而是
$k,等等。如果循环的计数器是一个已经存在并且名字有意义的变量,本规范并不适用。
例如: 1 for ($i = 0; $i $outer_size; $i++) 2 { 3 for ($j = 0; $j
$inner_size; $j++) 4 { 5 foo($i, $j); 6 } 7 } view plain | print | copy
to clipboard | ?函数名称: 函数也应该描述性地命名。这里我们并非在用 C
编程,我们不希望写出诸如stristr()此类的函数来。同上,使用单词间用单下划线分隔的小写名称。函数名称中某处最好有一个动词。较好的函数名
称如print_login_status(),
get_user_data(),等等。函数参数:参数遵循和变量名字相同的约定。我们不希望一堆这样的函数:do_stuff($a,
$b,
$c)。在大部分情况下,我们希望仅仅看看函数的声明,就知道怎样使用它。总结:
这里的基本哲学是不要为了偷懒而伤害了代码的清晰。但是,必须由一些常识来掌握这种平衡;例如,
print_login_status_for_a_given_user() 做得就过火了这个函数命名为
print_user_login_status() 更好些, 或只是 print_login_status()。
代码布局新建文件的标准头部:这里是一个头部的模版,它应当包含在每个 phpBB
文件开始 1
/***************************************************************************
2 &nb<

PHP规范1.
为什么要编码规范
•编码规范对于程序员而言尤为重要,有以下几个原因:1.在一个软件的生命周期中,80%的花费用于维护。

2.几乎没有任何一个软件在其整个生命周期中均由最初的开发人员来维护。

3.编码规范可以改善软件的可读性,可以让程序员尽快而彻底地理解新的代码。

4.如果将源码作为产品发布,就需要确认它是否被很好地打包并且清晰无误,和其他已构建的任何产品一样。

2.
概要
•用四个空格代替tab缩进。•去掉PHP文件底部的“?>”。•每行程序一般少于80字符,超出部分,分成多行书写。•每行只写一条语句,不允许把多个短语句写在一行中。•应为文件和函数添加注释。•应及时删除废除的注释代码。•变量、函数的命名应规范。

3. 编辑器设定3.1.
缩进所有的缩进使用空格取代Tab制表符。PHP文件采用4个空格的缩进,HTML文件以及HTML文件中嵌入的Javascript代码采用2个空格的缩进;单独的
Javascript以及CSS文件采用4个空格的缩进。

3.2. 字符编码所有PHP、HTML文件均保存为No Bom UTF-8的字符编码。

4. 代码布局4.1. 文件底部去掉文件底部 “?>”。

4.2.
相对独立的程序块之间、变量说明之后必须加空行示例:如下例子不符合规范复制代码 代码如下:if { … // program
code}$repssn_ind = $ssn_data[‘index’]->repssn_index;$repssn_ni
= $ssn_data[‘index’]->ni;应如下书写:

if { … // program code}

$repssn_ind = $ssn_data[‘index]->repssn_index;$repssn_ni =
$ssn_data[index]->ni; 4.3.
较长的语句要分成多行书写一行程序需小于80字符

较长的语句要分成多行书写,长表达式要在低优先级操作符处划分新行,操作符放在新行之首,划分出的新行要进行适当的缩进,使排版整齐,语句可读。

循环、判断等语句中若有较长的表达式或语句,则要进行适应的划分,长表达式要在低优先级操作符处划分新行,操作符放在新行之首示例:复制代码 代码如下:$perm_count_msg->len =
NO7_TO_STAT_PERM_COUNT_LEN + STAT_SIZE_PER_FRAM * strlen;

$act_task_table[$frame_id * STAT_TASK_CHECK_NUMBER +
$index]->occupied = $stat_poi[index]->occupied;

$act_task_table[taskno]->duration_true_or_false =
sys_get_sccp_statistic_state;

if (($taskno < $max_act_task_number)&& (n7stat_stat_item_valid
{ … // program code}

for ($i = 0, $j = 0; ($i <
$bufferKeyword[‘word_index’]->word_length) && ($j <
new_keyword->word_length); $i++, $j++){ … // program code} 4.4.
一行只写一条语句不允许把多个短语句写在一行中,即一行只写一条语句。示例:如下例子不符合规范

$rect->length = 0; $rect->width = 0;应如下书写:$rect->length =
0;$rect->width = 0;4.5.
始终包含大括号这是因为懒于多敲两个字符而给代码清晰带来问题的又一个情形。

示例:如下例子不符合规范复制代码
代码如下:if do_stuff do_stuff do_stuff();for ($i = 0; $i < $size;
$i++) do_stuff;应如下书写复制代码
代码如下:if { do_stuff{ do_stuff();}for ($i = 0; $i < $size; $i++){
do_stuff();} 4.6. switch写法示例:如下例子符合规范复制代码 代码如下:switch (){case ‘1′: ..program
break;case ‘2′: ..program break;}4.7.
大括号放在哪儿程序块的分界符应各独占一行并且位于同一列,同时与引用它们的语句左对齐。

而在函数体的开始、类的定义、以及if、for、do、while、switch、case语句中的右大括号应放在行尾,
左大括号应与右大括号所在行的行首处在同一列

示例:如下例子不符合规范复制代码
代码如下:for { … // program code}

if { … // program code}

function example_fun(){ … // program code}应如下书写:for { … //
program code}

if { … // program code}

function example_fun(){… // program code} 4.8.
符号之间使用空格采用这种松散方式编写代码的目的是使代码更加清晰。

由于留空格所产生的清晰性是相对的,所以,在已经非常清晰的语句中没有必要再留空格,如果语句已足够清晰则括号内侧不需要加空格,多重括号间不必加空格。在长语句中,如果需要加的空格非常多,那么应该保持整体清晰,而在局部不加空格。给操作符留空格时不要连续留两个以上空格。

示例:如下例子不符合规范复制代码
代码如下:$i=0;if …if …for …$i=?0:1;do_stuff; 应如下书写:复制代码 代码如下:$i = 0;if …if …for ($i =
0; $i < $size; $i++) …$i = ? 0 : 1;do_stuff; 4.9.
字符串连接符当使用字符串连接符时必须在句点两侧加上空格。

示例:如下例子不符合规范复制代码
代码如下:$str =
澳门新葡萄京官网首页 1‘;$str =
澳门新葡萄京官网首页 2‘;应如下书写:$str =
澳门新葡萄京官网首页 3‘; 4.10.
空行的使用谁也不愿意看到挤在一堆的无序的代码。我们在写代码的时候总是会利用一些空行来增加代码可读性。合理的利用空格来区分代码段会使代码的逻辑思路更加明确。我们强行规定的空行有以下两种情况:


之前必须有且只有1个空行•两个函数之间必须有1个空行。•return、die、exit之前如果有其他语句的情况下应加上一个空行。在代码中我们不允许在行尾有多余的空格。

5. 注释5.1. 文件头部模板/*** ShopEx网上商店 文件中文名称*
类或者文件的说明,此处可以使用html** @package* @version $Id$*
@copyright 2003-2008 Shanghai ShopEx Network Tech. Co., Ltd.* @license
Commercial*
=================================================================*/5.2.
函数头部注释每个函数之前应当有注释,告诉一个程序员使用这个函数所需要知道的事情。一个最小化的注释应包括:每个参数的意义,期望的输入,函数的输出。注释还应当给出在错误条件下这个函数的行为。其他人不必察看这个函数的代码,就可以自信地在自己的代码中调用这个函数。

另外,为任何技巧性的,晦涩的或者并非显而易见的代码添加注释,无疑是我们应该做的事情。对文档尤其重要的是你的代码所做的任何假设,或者它正确运转的前提。任何一个开发者应该能够查看应用程序的任意部分,并且在合理的时间内断定发生了什么。复制代码 代码如下: /** * some_func *
函数的含义说明 *

这部分可以随意输入html

* 因为这是phpdocument的约定。 * * @param mixed $arg1 参数一的说明 *
@param mixed $arg2 参数二的说明 * @access public * @return bool */
5.3. 删除废除的注释废除的注释,注释的代码要及时删除

5.4.
常量加注释对于所有有物理含义的变量、常量,如果其命名不是充分自注释的,在声明时都必须加以注释,说明其物理含义。变量、常量、宏的注释应放在其上方相邻位置或右方。

示例:复制代码 代码如下:// active
statistic task numberDefine(‘MAX_ACT_TASK_NUMBER’,1000)

Define(‘MAX_ACT_TASK_NUMBER’,1000); // active statistic task number
5.5.
注释位置注释应与其描述的代码相近,对代码的注释应放在其上方或右方相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。

示例:如下例子不符合规范

例1:复制代码 代码如下:// get replicate
sub system index and net indicator$repssn_ind =
$ssn_data[$index]->repssn_index;$repssn_ni =
$ssn_data[$index]->ni;例2:$repssn_ind =
$ssn_data[$index]->repssn_index;$repssn_ni =
$ssn_data[$index]->ni;// get replicate sub system index and net
indicator应如下书写// get replicate sub system index and net
indicator$repssn_ind =
$ssn_data[$index]->repssn_index;$repssn_ni =
$ssn_data[$index]->ni;5.6.
数据结构声明加注释数据结构声明,必须加以注释。对数据结构的注释应放在其上方相邻位置,不可放在下面;对结构中的每个域的注释放在此域的右方。

示例:按如下形式说明复制代码 代码如下://
sccp interface with sccp user primitive message
name$sccp_user_primitive = array( ‘N_UNITDATA_IND’ => 1, // sccp
notify sccp user unit data come ‘N_NOTICE_IND => 2, // sccp notify
user the No.7 network can not transmission this message N_UNITDATA_REQ
=> 3 // sccp user’s unit data transmission request ) 5.7.
全局变量注释全局变量要有较详细的注释,包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明。

5.8. 注释缩排注释与所描述内容进行同样的缩排,
可使程序排版整齐,并方便注释的阅读与理解。

示例:如下例子不符合规范复制代码
代码如下:function example_fun(){ // code one comments CodeBlock One

// code two comments CodeBlock Two}应改为如下布局:复制代码 代码如下:function example_fun(){
//fdgfd CodeBlock One

// code two comments CodeBlock Two}5.9.
将注释与其上面的代码用空行隔开示例:如下例子,显得代码过于紧凑。复制代码 代码如下:// code one commentsprogram
code one// code two commentsprogram code two应如下书写// code one
commentsprogram code one

// code two commentsprogram code two 5.10.
连续case注释对于switch语句下的case语句,如果因为特殊情况需要处理完一个case后进入下一个case处理,必须在该case语句处理完、下一个case语句前加上明确的注释。这样比较清楚程序编写者的意图,有效防止无故遗漏break语句。

示例:复制代码 代码如下:switch { case
‘CMD_INIT’: echo “i equals 0”; break; case ‘CMD_START: echo “i equals
1”;// now jump into case CMD_A case ‘CMB_A’: echo “i equals 2”;
break;}5.11. 结构体声明代码中代表结构体的数组变量,要提前声明。

示例:复制代码 代码如下:function
example_fun(){ $student = array( ‘name’ => ‘小明’, //名称 ‘addr’
=> ‘详细地址’, //地址 ‘sex’ => ‘男’, //性别 ‘city’ => ‘上海’
//城市 )} 5.12. 注释格式注释格式统一,单行注释必须使用“// ……
”,多行使用一对/*…*/

示例:如下例子不符合规范。复制代码
代码如下:/* if receive_flag is TRUE *//* if receive_flag is FALSE
*/if 应如下书写:复制代码 代码如下:/*
if receive_flag is TRUEif receive_flag is FALSE */if 5.13.
注释以中文为主注释应考虑程序易读及外观排版的因素,使用的语言若是中、英兼有的,建议多使用中文,除非能用非常流利准确的英文表达。

6. 命名规定6.1. 禁止拼音命名法代码中禁止用拼音命名法。

6.2. 变量命名变量名应当全部小写,并且词语之间以单个下划线分隔。

例如: $current_user 是正确的, 但是 $currentuser 和 $currentUser
就不正确。

名称应当是描述性的,并且简明。我们自然不希望使用冗长的句子作为变量名,但是多输入几个字符总好于疑惑于某个变量到底是干什么用的。

6.3.
函数命名使用单词间用单下划线分隔的小写名称,允许动宾词组为执行某操作的函数命名。如果是OOP方法,可以只有动词。允许系表函数命名。

示例:复制代码 代码如下:

function print_record function input_record() function
get_current_color动词表:add / edit / remove begin / end create /
destroyfirst / last get / release get / setincrement / decrement put /
getlock / unlock open / closemin / max old / new start / stopnext /
previous source / target show / hidesend / receivecut / paste up / down

系词表: is has对于私有方法,以_开头。

6.4.
循环计数器允许使用一个单字符变量名的唯一情形是当它作为一个循环计数器的时候。在这种情况下,外层循环的计数器应当始终是
$i。如果有一个循环处于这个循环的内部,它的计数器应当是 $j,进而是
$k,等等。如果循环的计数器是一个已经存在并且名字有意义的变量,本规范并不适用。

例如:复制代码 代码如下:for ($i = 0; $i
< $outer_size; $i++){ for ($j = 0; $j < $inner_size; $j++){ foo;
}}6.5.
函数参数参数遵循和变量名字相同的约定。我们不希望一堆这样的函数:do_stuff。在大部分情况下,我们希望仅仅看看函数的声明,就知道怎样使用它。

7. 可读性7.1.
运算符的优先级注意运算符的优先级,并用括号明确表达式的操作顺序,避免使用默认优先级。防止阅读程序时产生误解,防止因默认的优先级与设计思想不符而导致程序出错。

示例:下列语句中的表达式复制代码
代码如下:$word = | $low && if ) 如果书写为$high << 8 | $low$a | $b
&& $a & $c$a | $b < $c & $d由于$high << 8 | $low = | $low,$a |
$b && $a & $c = ,不会出错,但语句不易理解;$a | $b < $c & $d = $a |
造成了判断条件出错。

7.2. 避免数字,使用常量避免使用不易理解的数字,用有意义的常量来替代。

示例:如下的程序可读性差。复制代码
代码如下:if ($trunk[$index]->trunk_state == 0){
$trunk[$index]->trunk_state = 1; … // program code}
应改为如下形式。复制代码
代码如下:definedefine

if ($trunk[$index]->trunk_state == TRUNK_IDLE){
$trunk[$index]->trunk_state = TRUNK_BUSY; … // program code}
7.3. 源程序中关系较为紧密的代码应尽可能相邻便于程序阅读和查找。

示例:以下代码布局不太合理。复制代码
代码如下:$rect->length = 10;$char_poi = $str;$rect->width =
5;若按如下形式书写,可能更清晰一些。复制代码 代码如下:$rect->length =
10;$rect->width = 5; // 矩形的长与宽关系较密切,放在一起。$char_poi
= $str;

8. 函数8.1.
接口函数参数的合法性检查函数参数的合法性检查应由函数的调用者负责,接口函数做必要性合法性检查。

总结为:以外为主,以内为辅,内部不强制。

8.2. 函数规模函数的规模限制在100行以内,不包括注释和空格行。

8.3. 一个函数仅完成一件功能8.4.
不要设计多用途面面俱到的函数除调度函数外,多功能集于一身的函数,很可能使函数的理解、测试、维护等变得困难

8.5.
多段代码重复同一件事情如果多段代码重复做同一件事情,那么在函数的划分上可能存在问题。若此段代码各语句之间有实质性关联并且是完成同一件功能的,那么可考虑把此段代码构造成一个新的函数。

9. 质量保证9.1. 兼容性9.2.
三元运算符三元运算符,在一行代码里只允许使用一级

三元运算符只应该用来做简单的事情。它们只适合拿来做赋值用,根本不是用来做函数调用或者任何复杂的事情的。如果使用不当,它们会影响可读性,所以不要沉迷于使用它们来减少打字。

示例:不应该使用它们的地方 && ? do_stuff : do_stuff;

示例:使用它们的合适地方$min = ? $i : $j;

9.3. 初始化变量变量使用前应初始化,error_reporting 将加入
E_NOTICE。意味着,变量未初始化将报错。这个问题最容易在检查 HTML
表单传递了什么变量时出现。这些错误可以通过使用内嵌的
isset函数检查一个变量是否被设置来避免。

示例: 老办法if …新办法:if …if …9.4. 引用字符串在 PHP
中有两种不同的方式引用字符串——使用单引号或使用双引号。主要区别是:解析器在双引号括起的字符串中执行变量替换,却不在单引号括起的字符串中执行。因此,应当始终使用单引号,除非你确实需要对字符串进行变量替换。这样,我们可以避免让解析器解析一堆不需要执行替换的字符串的麻烦。同样,如果你使用字符串变量作为函数调用的一部分,你不需要用引号把那个变量括起来。同样,那只会给解析器增加不必要的工作。无论如何,要注意几乎所有双引号中的转义序列在单引号中都不会起作用。如果这条规范使你的代码难以阅读的话,要小心,并且放心地打破它。

示例:如下例子不符合规范复制代码
代码如下:$str = “This is a really long string with no variables for the
parser to find.”;do_stuff;应如下书写:复制代码 代码如下:$str = ‘This is a really long
string with no variables for the parser to
find.’;do_stuff;当由于可读性的原因不得不使用双引号作为引用符时,注意其中所有的变量需用{}包围:$str
= ” This is ‘{$what}’ with no variables for the parser to find.”

9.5. 关联数组的键名在 PHP
中,使用一个不用引号括起来的字符串作为一个关联数组的键名是可以运行的。我们不想这样做——为了避免混乱,这个字符串应当用引号括起来。注意,这只是当我们使用字符串时的情况,不是当我们使用变量时的情况。示例:如下例子不符合规范

$foo = $assoc_array[blah];应如下书写:$foo = $assoc_array[‘blah’];

9.6.
简化运算符简化自增运算符是导致可读性问题的仅有的简化运算符。这些运算符不应当被用作表达式的一部分。然而,他们可以独占一行使用。在表达式中使用它们。

示例:如下例子不符合规范复制代码
代码如下:$array[++$i] = $j;$array[$i++] =
$k;应如下书写:$i++;$array[$i] = $j;$array[$i] = $k;$i++;9.7. if
以及else
if的写法当条件语句中的条件存在多个,并且有变量值的判断的时候,需要把变量的判断语句放在其他的条件语句之前。

示例:如下例子不符合规范复制代码
代码如下:if (function_exists && $val == 1){}应如下书写:if ($val == 1
&& function_exists{}虽然在 PHP 中else if 和 elseif
的作用基本上是一样的。但是为了代码的统一性(也有传言 else if
会出现不稳定的情况),我们要求将 elseif 之间不保留空格:if {}elseif
{}9.8.
输入变量的初始化无论是函数的参数还是通过URL传递的变量,在调用之前均必须对其进行预处理以及设定默认值。

字符串必须进行trim及转义的处理,并且如果变量的值是在我们预计的范围之内,需要对变量的非法值做出相应的处理;对于数字型的变量则需要进行intval或者floatval的处理。

9.9.
require和include在程序中需要使用包含文件的时候我们要求使用require_once或者include_once,不允许使用require或者include。

对于程序必须包含的文件只能采用require_once,而对于某些有条件包含的文件在引用时只能使用include_once。

9.10. 文件命名文件名应当全部小写,并且词语之间以单个下划线分隔。

例如: current_user.php 是正确的, 但是 currentuser.php 和
currentUser.php 就不正确。

名称应当是描述性的,并且简明。我们自然不希望使用冗长的句子作为文件名,但是多输入几个字符总好于疑惑于某个文件到底是干什么用的。

10. SQL语法10.1. SQL
代码布局既然我们都在使用不同的编辑器设置,不要尝试去做诸如在 SQL
代码中实现列对齐此类的麻烦事。要做的是,不管用何种方法,把语句断行到它们单独的行上去。这里有一个
SQL 代码看上去应该是什么样子的示例。注意在哪里断行,大写,和括号的用法。

例如:复制代码 代码如下:SELECT field1 AS
something, field2, field3FROM `table` a, `table` bWHERE AND 10.2.
表名和字段值SQL语句中的表名与字段名避免使用保留字;同时所有字段值的变量名,如果是数值型,需要强制类型转换。intval,floatval…

10.3. SQL select
语句在已知需要查询的字段的前提下,不允许使用如下的代码:

SELECT * FROM
`mytable`取而代之的写法是将每一个字段名写上去,请不要偷懒。SELECT
col1, col2, col3 FROM `mytable`在需要获得已知记录数量情况下,请使用
LIMIT offset, count 的方式,尽量不要使用无 LIMIT 的 SELECT 语句。

在需要或者满足条件的记录数量的情况下,请使用 SELECT count FROM
的方式,尽量不要使用 SELECT col1 FROM 的方式。

需要进行逻辑运算的时候,尽量不要使用不等于,可以使用大于或者小于的方式。

10.4. SQL insert 语句SQL INSERT
语句可以写成两种不同方式。或者你明确指明要插入的列,或者你已经知道数据中各列的顺序,不用详细指定它们。我们希望使用前一种方法,也就是详细说明插入哪些列。这意味着应用程序代码不会依赖于数据库中字段的顺序,也不会因为我们增加另外的字段而崩溃。

例如:# 这不是我们想要的复制代码
代码如下:INSERT INTO `mytable`VALUES (‘something’, 1, ‘else’)#
这是正确的。复制代码 代码如下:INSERT INTO
`mytable` (column1, column2, column3)VALUES (‘something’, 1,
‘else’)11. smarty语法11.1. 界定符界定符为

11.2.
双引号、单引号为了避免dreamweaver将Smarty语句中的双引号改写为”,我们要求在Smarty的花括号中不允许使用双引号,而是使用单引号。

错误的写法:匿名用户正确的写法:匿名用户11.3.
有条件设置HTML属性值当需要在模板中有条件的设置HTML元素属性值的时候,我们要求所有语句均包含在双引号之内。错误的代码:复制代码 代码如下:

0}>”promote_goods””normal_goods”>

正确的写法:复制代码 代码如下:

11.4.
条件修饰符在smarty中可以用eq、neq、gt、lt等来分别表示==、!=、>、

当Smarty语句出现在HTML标签内时不允许使用==、!=这类修饰符,如果使用了这类修饰符有可能导致该符号或者其他的HTML相关符号被Dreamweaver自动转义。

总之,尽量使用eq、gt等这类条件修饰符,避免直接使用==、>。

发表评论

电子邮件地址不会被公开。 必填项已用*标注