PHP_程序编码规范

《PHP_程序编码规范》由会员上传分享，免费在线阅读，更多相关内容在教育资源-天天文库。

PHP程序编码规范 Anyviolationtothisguideisallowedifitenhancesreadability. 所有的代码都要变成可供他人容易阅读的 良好的代码书写习惯+良好的注释习惯+PhpDocumentor=程序说明书 整理日期:2014-05-06 参考修改自: .NET编程规范 华为编程规范 JavaScript程序编码规范(cloudwater译) PHP开发规范(未知出处) PHPCodingStandard(FredrikKristiansen/DBMedialab) 等...... 前言 第1章排版规则 1.1缩进 1.2空格规则 1.2.1逻辑运算符前后必须加空格 1.2.2多个参数分隔时必须加空格 1.2.3语法关键字后必须加空格 1.2.4字符串和变量连接规则 1.3换行 1.3.1较长的语句(>80字符) 第2章命名规范 2.1变量命名 2.1.1局部变量 2.1.2全局变量命名 2.1.3静态变量命名 2.1.4引用变量和函数返回引用 2.1.5临时变量命名 2.1.6方法中参数命名 2.2命名定义/全局常量 2.3类命名 2.3.1接口命名原则 2.3.2Exception命名原则 2.3.3类库命名 2.3.4方法命名 2.3.5方法/函数命名修饰 2.3.6类属性命名 2.3.7私有属性与私有方法命名 2.3.8对象命名 2.4缩写词不要全部使用大写字母 2.5函数命名 第3章版式规则 3.1语义分隔 3.2圆括号规则 PHP程序编码规范 3.3方法/函数 3.4关键字 3.4.1if语句 3.4.2for语句 3.4.4do语句 3.4.5switch语句 3.4.6try语句 3.4.7return语句 第4章编程规范 4.1数组定义规则 4.2不要采用缺省方法测试非零值 4.3通常避免嵌入式的赋值 4.4布尔逻辑类型 4.5别在对象架构函数中做实际的工作 4.6switch格式 4.7Continue和Break 4.8?: 4.9其他杂项 4.9.1类定义文件中,定义体之外不得出现诸如echo、print等输出语句; 4.9.2在HTML网页中尽量不要穿插PHP代码 4.9.3没有含义的数字 4.9.4PHP文件扩展名 4.9.5总是将恒量放在等号/不等号的左边 4.10SQL规则 4.10.1输出网页的页面不出现SQL语句 4.10.2进行SQL执行的数据必须进行有效性检测 第5章注释规则 5.1一般规则 5.2方法/函数注释 5.3类注释 5.4记录所有的空语句 5.5用if(0)来注释外部代码块 5.6版权信息 第1章排版规则 1.1缩进 缩进对齐统一使用一种方式;只用4个空格或者只用TAB。 说明:根据实际使用的环境来决定。一些编辑器自动转换TAB为4个空格的距离,但有些也会转换为8 个空格。 块开头对齐赋值: $book_name ='';//书名 $new_book_name ='';//新书名 $new_book_page_count=0;//新书页计数 说明:一般在函数的开头把所有用到的内部变量都初始化一次,这样可以防止程序的未定义错误,并且 对函数内部变量有个直观的一览。适用于定长字体。 1.2空格规则 空格应在以下情况时使用: l跟在((左括号)后面的关键字应被一个空格隔开。 while(true){ 函数名与左括号之间不应该有空格。这能帮助区分关键字和函数调用。 functionmyfun(){ 所有的二元操作符,除了左括号和左方括号应用空格将其与操作数隔开。 一元操作符与其操作数之间不应有空格,除非操作符是个单词,比如typeof。 每个在控制部分,比如for语句中的;(分号)后须跟一个空格。 for($i=0;$i<10;$i++){ 每个,(逗号)后应跟一个空格。l 1.2.1逻辑运算符前后必须加空格 正确$a==$b; 正确$a++;$a––; 错误$a==$b; $a==$b; 错误$a++;$a––; 备注:加一减一运算符不能加空格。 1.2.2多个参数分隔时必须加空格 错误 $g_pro,$g_user,g_show; $g_pro,$g_user,$g_show; get_db_info($host,$user,$passwd); get_db_info($host,$user,$passwd); 1.2.3语法关键字后必须加空格 if,for,while,switch等关键字... 例如: 正确for($i=0;$i<10;$i++) 错误for($i=0;$i<10;$i++) 1.2.4字符串和变量连接规则 字符串与变量连接使用'.'号时,必须在'.'前后加空格,使用”号自动转义变量时必须在变量前后加”{}” 。 正确$my_name='file_'.$var1; 错误$my_name='file_'.$var1; 正确 错误 $my_name="file_{$var1}"; $my_name="file_$var1"; 正确$my_name=$_POST['name']; 错误$my_name=$_POST[name]; 1.3换行 每行一个语句,除非这些语句有很密切的联系,否则每行只写一个语句。用空行来将逻辑相关的代码 块分割开可以提高程序的可读性。相对独立的程序块之间、变量说明之后必须加空行。 示例:如下例子不符合规范。 if(!valid_ni($ni)){ ...//programcode } $repssn_ind=$ni; 应如下书写 if(!valid_ni($ni)){ ...//programcode } $repssn_ind=$ni; 1.3.1较长的语句(>80字符) 要分成多行书写,长表达式要在低优先级操作符处划分新行,操作符放在新行之首,划分出的新行要进 行适当的缩进,使排版整齐,语句可读。 示例: if((tasknoGetTimeOfError(); $error_processor=osErr->GetErrorProcessor(); } 变量名字应该使用名词或者形容词+名词的方式。如$value,$new_value。 2.1.2全局变量命名 全局变量使用g前缀。 例: global$gLog; global&$rgLog; 2.1.3静态变量命名 静态变量使用s前缀,如:$s_value。 2.1.4引用变量和函数返回引用 引用必须带‘r’前缀 理由: 使得类型不同的变量容易辨认,它可以确定哪个方法返回可更改对象,哪个方法返回不可更改对象。 如:$r_var。 function&rStatus(){}; ps:关于用返回引用来加快运行速度一说,有文章指出并不明显。 2.1.5临时变量命名 不要将在循环中频繁使用的临时变量如$i,$j等用于其它用途。 2.1.6方法中参数命名 参数的名字使用Camel命名方法(首字母小写) ,在首字符后的所有字都按照类命名规则首字符大写。 参数的名字应该是描述性的,参数的名字应该具有自描述性,也就是说参数的名称可以描述参数在大多数 情况下的含义,参数的类型也是可以从参数的名字推断出来的。参数的名字是基于参数的含义而不是参数 的类型。 理由: 可以区分方法中的一般变量。 你可以使用与类名相似的名称而不至于产生重名冲突。 例如: classNameOneTwo{ functionStartYourEngines(&$rSomeEngine,&$rAnotherEngine); } 2.2命名定义/全局常量 全局常量所有字母都大写,用'_'分隔每个单词。 理由: 这是命名全局常量的传统。你要注意不要与其它的定义相冲突。 例如: define("HELLO_WORLD","Helloworld!"); 2.3类命名 用Pascal命名规则,也就是用英文的大小写来分隔单词,包括首个单词,所有单词的首字母大写,如 PageManager; 尽量谨慎的使用缩写,不要用下划线作类名单词连接符。 在类中,方法放到属性定义前边、公用方法放到专用方法前边。 在为类命名前首先要知道它是什么。如果通过类名的提供的线索,你还是想不起这个类是什么的话,那 么你的设计就还做的不够好。 超过三个词组成的混合名是容易造成系统各个实体间的混淆,再看看你的设计, 尝试使用(CRCSession card)看看该命名所对应的实体是否有着那么多的功用。 对于派生类的命名应该避免带其父类名的诱惑, 一个类的名字只与它自身有关, 和它的父类叫什么无关。 有时后缀名是有用的,例如:如果你的系统使用了代理(agent)那么就把某个部件命名为, “下载代理” (DownloadAgent)用以真正的传送信息。 一般情况下,一个类对应到一个文件,当一些类关系紧密时,可以存放在一个文件中。存放类的文件采 用classname.class.php方式命名。所有系统文件名均为小写。 2.3.1接口命名原则 接口名字在类的原则上加前缀I。 例如:IComponent(描述性名词)、ICustomAttributeProvider(名词短语)、IPersistable(形容词) 等。 有的类,必须用字母I作为类名前缀,而又不是一个接口。这是可以接受的,因为有的类名就是I开头 的,例如:IdentityStore。这种情况和接口的区别在于其第二个字母是小写的。 有的时候,定义完一个接口之后,也会定义一个类作为接口的标准实现。该类和该接口应该有类似的名 字,唯一的区别就是接口名称前缀为字母I。 如:IComponent和它的标准实现classComponent{}。 2.3.2Exception命名原则 异常的命名以“Exception”为后缀。 2.3.3类库命名 目前命名空间正在越来越广泛的被采用,以避免不同厂商和团体类库间的类名冲突。 当尚未采用命名空间的时候,为了避免类名冲突,一般的做法是在类名前加上独特的前缀,两个字符就 可以了,当然多用一些会更好。 例如 JohnJohnson的数据结构类库可以用Jj做为前缀,如下: classJjLinkList{} 另一种折中方式是建立包含类库目录 (事实上Java也是这么做的)以不通的目录代表不同的命名空间。 例如: Microsoft的数据库相关类库可以在: /classes/com/Microsoft/Database/DbConn.php Apache的数据库相关类库可在: /classes/org/apache/Database/DbConn.php 2.3.4方法命名 采用与类命名一致的规则 理由: 使用所有不同规则的大部分人发现这是最好的折衷办法。 ps:这种方法和PHP并不像但是和java匹配,而又与js/C#类似,程序界够乱套的。 例如: classNameOneTwo{ functionDoIt(){}; functionHandleError(){}; } 2.3.5方法/函数命名修饰 通常每个方法和函数都是执行一个动作的,所以对它们的命名应该清楚的说明它们是做什么的:用 CheckForErrors()代替ErrorCheck(),用DumpDataToFile()代替DataFile()。这么做也可以使功能和 数据成为更可区分的物体。 方法使用英文的大小写来分隔单词,命名建议使用动词+名词的方式,单词的首字母大写。不要采用不常 用的缩写,如Where2Go();使用常用的缩写时,只大写首字母,如GetHtml()。 有时后缀名是有用的: Max-含义为某实体所能赋予的最大值。 Cnt-一个运行中的计数变量的当前值。 Key-键值。 例如:RetryMax表示最多重试次数,RetryCnt表示当前重试次数。 有时前缀名是有用的: Is-含义为问一个关于某样事物的问题。无论何时,当人们看到Is就会知道这是一个问题。 Get-含义为取得一个数值。 Set-含义为设定一个数值 r-小r前缀用于修饰返回引用的地方法与函数。 例如:$IsHitRetryLimit。 function&rStatus(){}; functionDoSomething(&$rStatus){}; 2.3.6类属性命名 使用英文名词、动词,以大写字母作为词的分隔,其他的字母均使用小写,单词的首个字母 使用大写,不使用下划线,对于类属性为某个对象变量,则以字符串Object为后缀,例: classUserAccount{ $TableName =''; $DatabaseObject=''; } 2.3.7私有属性与私有方法命名 以_开头,如private$_PrivateValue; privatestatic$_sPrivateStaticValue; privatefunction_Initialize(){...}; 2.3.8对象命名 使用类名称为变量前缀,所有字母都使用大写,以字符串_obj为后缀, 例:$input_obj=newInput; ps:经测试发现如果遇到比较长的类名的话精简变量名字是有必要的, 前提是一眼就能看出名字的意义, 变量过长的命名感觉导致书写困难,也影响程序可读性。 例:$front_obj=JdFrontController::getInstance(); 2.4缩写词不要全部使用大写字母 无论如何,当遇到以下情况,你可以用首字母大写其余字母小写来代替全部使用大写字母的方法来表示 缩写词。 使用:GetHtmlStatistic. 不使用:GetHTMLStatistic. 理由: 当命名含有缩略词时,人们似乎有着非常不同的直觉。统一规定是最好,这样一来,命名的含义就完全可以预知了。 举个NetworkABCKey的例子, 注意C是应该是ABC里面的C还是key里面的C, 这个是很令人费解的。 有些人不在意这些,其他人却很讨厌这样。所以你会在不同的代码里看到不同的规则,使得你不知道怎么 去叫它。 例如 classFluidOz//不要写成FluidOZ classGetHtmlStatistic//不要写成GetHTMLStatistic ps:不过有时也要是情况而定,如PDO类库本身全大写,那么classMyPDOextendsPDO{...}也就 说得过去了,如果PDO小写有可能起反作用,主要目的在于容易理解,而不是做样子。 2.5函数命名 函数名字采用CGNU的惯例,所有的字母使用小写字母,使用'_'分割单词。 理由: 这样容易区分类方法? ps:此条有待研究,函数与方法区分微小,人为扩大区分不会起到反作用么?调用的时候明显的->操作 方还不够清晰么? 例如: functionsome_bloody_function(){} 完成一组功能的函数放到一个文件中,存放函数的文件采用name.func.php命名。 第3章版式规则 3.1语义分隔 各个函数、方法之间应该采用空行间隔;ps:}结束大括号要有空行 同一个函数中联系紧密的语句之间可以不换行,其他情况需要换行。 3.2圆括号规则 函数名与括号之间不需要加空格、语法关键字后的括号必须加空格。 正确for($i=0;$i<10;$i++) strlen($my_name); 错误for($i=0;$i<10;$i++) strlen($my_name); 3.3方法/函数 函数名与((左括号)之间不应该有空格。)(右括号)与开始程序体的{(左大括号)之间应插入一个空格。 函数程序体应缩进四个空格。}(右大括号)与声明函数的那一行代码头部对齐。 functionouter($c,$d){ $e=$c*$d; functioninner($a,$b,$e){ return($e*$a)+$b; } returninner(0,1,$e); } 如果函数是匿名函数,则在function和((左括号)之间应有一个空格。如果省略了空格,否则会让人感觉函 数名叫作function。 $a=function($e){ return$e; }; 3.4关键字 if、for、do、while、case、switch、default等语句自占一行,且if、for、do、while等语句的执行 语句部分无论多少都要加括号{}。 示例: 如下例子不符合规范: if(NULL==$rUserCR)return; 应如下书写: if(NULL==$rUserCR){ return; } if这个规范是最容易出错的地方,不规范的写法在程序重构或修改的时候很容易造成疏忽。 3.4.1if语句 if语句应如以下格式: if(condition){ statements; } if(condition){ statements; }else{ statements; } if(condition){ statements; }elseif(condition){ statements; }else{ statements; } 3.4.2for语句 for语句应如以下格式: for(initialization;condition;update){ statements; } 3.4.3while语句 while语句应如以下格式: while(condition){ statements; } 3.4.4do语句 do语句应如以下格式: do{ statements; }while(condition); 不像别的复合语句,do语句总是以;(分号)结尾。 3.4.5switch语句 switch语句应如以下格式: switch(expression){ caseexpression: statements; default: statements; } 每个case与switch对齐。这可避免过分缩进。 每一组statements(除了default应以break,return,或者throw结尾。不要让它顺次往下执行。 3.4.6try语句 try语句应如以下格式: try{ statements; }catch(variable){ statements; } 3.4.7return语句 一条有返回值的return语句不要使用()(括号)来括住返回值。 如果返回表达式,则表达式应与return关 键字在同一行,以避免误加分号错误。 第4章编程规范 系统统一使用时间戳time()作为时间标志,写入mysql时使用INT(10)类型写入,读取时可以使用公 共函数库中的getdate()将时间戳转换为标准时间格式; 引号统一使用'单引号,只有当引号重叠时才使用"双引号,这样每进程可以节省几百K内存; 统一使用,禁止使用格式。 4.1数组定义规则 数组定义和使用时中key值前后必须加单引号。 //正确 array( 'name' 'gender' ); =>'d5s.cn', =>'php' //错误 array( =>'d5s.cn', name gender=>'php' ); 4.2不要采用缺省方法测试非零值 不要采用缺省值测试非零值,也就是使用: if(FAIL!=f()) 比下面的方法好: if(f()) 即使FAIL可以含有0值,也就是PHP认为false的表示。在某人决定用-1代替0作为失败返回值的时 候,一个显式的测试就可以帮助你了。就算是比较值不会变化也应该使用显式的比较; 例如: if(!($bufsize%strlen($str))) 应该写成:if(($bufsize%strlen($str))==0)以表示测试的数值(不是布尔)型。 一个经常出问题的地方就是使用strcmp来测试一个字符等式,结果永远也不会等于缺省值。 非零测试采用基于缺省值的做法,那么其他函数或表达式就会受到以下的限制: 只能返回0表示失败,不能为/有其他的值。 命名以便让一个真(true)的返回值是绝对显然的,调用函数IsValid()而不是Checkvalid()。 Ps:最直接的体现就是PHP的ip2long函数,在5.2.10以前他返回-1表示出错,之后他返回false表示出错。 PHP程序编码规范 4.3通常避免嵌入式的赋值 有时候在某些地方我们可以看到嵌入式赋值的语句,那些结构不是一个少冗余,可读性强的好方法。 while($a!=($c=getchar())){ processthecharacter } ++和--操作符类似于赋值语句。因此,出于许多的目的,在使用函数的时候会产生副作用。使用嵌入 式赋值提高运行时性能是可能的。 无论怎样,程序员在使用嵌入式赋值语句时需要考虑在增长的速度和减少的可维护性两者间加以权衡。 例如: $a=$b+$c; $d=$a+$r; 不要写成: $d=($a=$b+$c)+$r; 虽然后者可以节省一个周期。但在长远来看,随着程序的维护费用渐渐增长,程序的编写者对代码渐渐 遗忘,就会减少在成熟期的最优化所得。 4.4布尔逻辑类型 大部分函数在FALSE的时候返回0,但是返回非0值就代表TRUE,因而不要用1(TRUE,YES,诸如 此类)等式检测一个布尔值,应该用0(FALSE,NO,诸如此类)的不等式来代替: if(TRUE==func()){ 应该写成: if(FALSE!=func()){ 4.5别在对象架构函数中做实际的工作 别在对象架构构造函数中做实际的工作,构造函数应该包含变量的初始化和(或)不会发生失败的操作。 理由: 构造不能返回错误。 例如: classDevice{ functiondevice(){/*initializeandotherstuff*/} functionopen(){returnFAIL;} }; $dev=newDevice; if(FAIL==$dev->open()){ exit(1); } ps:通过例子清晰表明,问题所在就是构造函数不能return. 所以不需要return的错误就没问题...(try下,出错就自动挂掉全部程序-_-;) 4.6switch格式 当一个case块处理后,直接转到下一个case块处理,在这个case块的最后应该加上注释。 ldefaultcase总应该存在,它应该不被到达,然而如果到达了就会触发一个错误。 l如果你要创立一个变量,那就把所有的代码放在块中。 例如 switch(...){ case1: ... l //FALLTHROUGH case2: { $v=get_week_number(); ... } break; default: } 4.7Continue和Break Continue和break其实是变相的隐蔽的goto方法。 Continue和break像goto一样,它们在代码中是有魔力的,所以要节俭(尽可能少)的使用它们。 使用了这一简单的魔法,由于一些未公开的原因,读者将会被定向到只有上帝才知道的地方去。 Continue有两个主要的问题: 它可以绕过测试条件。 它可以绕过等/不等表达式。 看看下面的例子,考虑一下问题都在哪儿发生: while(TRUE){ ... //Alotofcode ... if(/*somecondition*/){ continue; } ... //Alotofcode ... if($i++>STOP_VALUE)break; } 注意:"Alotofcode"是必须的,这是为了让程序员们不能那么容易的找出错误。 通过以上的例子,我们可以得出更进一步的规则:continue和break混合使用是引起灾难的正确方法。 ps:刚看还真没发现问题(悲剧),运行后发现问题所在... -18- PHP程序编码规范 4.8?: 麻烦在于人们往往试着在?和:之间塞满了许多的代码。以下的是一些清晰的连接规则: 把条件放在括号内以使它和其他的代码相分离。 如果可能的话,动作可以用简单的函数。 把所做的动作,?”“:”放在不同的行,除非他们可以清楚的放在同一行。 “, 例如: (condition)?funct1():func2(); 或 (condition) ?longstatement :anotherlongstatement; 4.9其他杂项 l l PHP标签统一使用,禁止使用格式。 使用完毕后的数组变量、对象变量、查询集合必须马上使用unset()、free_result()释放资源。 Ps:这个还有待验证效果,据说基本没效果,当前脚本运行中是不会释放内存的,我指的是脚本, 不是变量。 PHP文件中绝不能出现html语句(ps:非字符串状态的),html文件中尽可能避免出现PHP语句。 html文件必须通过w3c的html4检测认证(http://validator.w3.org/) 。 如果发觉您在程序中的命名只有少量能和其对应事物相匹配的话,请重新设计系统。 所有文件的名字均为小写,以兼容win/unix类系统 4.9.1类定义文件中,定义体之外不得出现诸如echo、print等输出语句; 理由: 出现这样的语句,应该当做出现bug来看。 4.9.2在HTML网页中尽量不要穿插PHP代码 循环代码和纯粹变量输出(类似于)除外。 理由 需要说明的是我们工作的上游,页面设计者的工作,假如在页面中穿插代码,将破坏结构,这应当是 我们需要避免的。 在这里的PHP代码只负责显示,多余的代码显然是不应该的。 4.9.3没有含义的数字 一个在源代码中使用了的赤裸裸的数字是不可思议的数字,因为包括作者,在三个月内,没人知道他它的 含义。例如: if(22==$foo){start_thermo_nuclear_war();} elseif(19==$foo){refund_lotso_money();} elseif(16==$foo){infinite_loop();} else{cry_cause_im_lost();} 在上例中22和19的含义是什么呢?如果一个数字改变了,或者这些数字只是简单的错误,你会怎么想? 使用不可思议的数字是该程序员是业余运动员的重要标志. 你应该用define()来给你想表示某样东西的数值一个真正的名字,而不是采用赤裸裸的数字,例如: define("PRESIDENT_WENT_CRAZY","22"); define("WE_GOOFED","19"); define("THEY_DIDNT_PAY","16"); if(PRESIDENT_WENT_CRAZY==$foo){start_thermo_nuclear_war();} elseif(WE_GOOFED==$foo){refund_lotso_money();} elseif(THEY_DIDNT_PAY==$foo){infinite_loop();} else{happy_days_i_know_why_im_here();} 现在不是变得更好了么? 4.9.4PHP文件扩展名 常见的PHP文件的扩展名有:html,.php,.php3,.php4,.phtml,.inc,.class... 这里我们约定: ·所有浏览者可见页面使用.html ·所有类、函数库文件使用.php 理由 ·扩展名描述的是那种数据是用户将会收到的。PHP是解释为HTML的。 4.9.5总是将恒量放在等号/不等号的左边, 例如: if(6==$errorNum)... 一个原因是假如你在等式中漏了一个等号,语法检查器会为你报错。第二个原因是你能立刻找到数值而 不是在你的表达式的末端找到它。需要一点时间来习惯这个格式,但是它确实很有用。 4.10SQL规则 在PHP中嵌入的SQL语句关键字全部采用大写; 表名和字段名要用反引号(`)引起来以防止因为字段名中包含空格而出现错误; 数据值两边用单引号’包括,并且应确保数据值中的单引号已经转义以防止SQL注入。 正确$sql=”SELECT`user`.`name`FROM`user`WHERE`id`=’$id’′′; 错误$sql=”selectname.userfromnamewhereid=$id”; 能使用多表查询一次查询的数据要一次读完,避免多次查询数据库,数据库使用完要关闭连接; Ps:貌似长连接和短连接还是有些说法的。 4.10.1输出网页的页面不出现SQL语句 理由: 这是n层结构的编程思想所致,每层的任务不同,虽然可以越权行使,可能这样很快捷,但我们不赞成这 么干。Ps:我理解就是view层是不应该直接调用数据库的,应该通过M层或者单独的数据库层才好。 4.10.2进行SQL执行的数据必须进行有效性检测 特殊符号: 对于MSSQLServer, ’%_[]这些符号都是在书写SQL语句中的特殊含义字符,在SQL执行前需要对 这些字符进行处理。 脚本符号: 对于PHP脚本标记,如,在进入数据库前需要检测处理。 理由 这是数据库编程的一个约定,很多参考书上也是这么说,这里需要强调一下。 第5章注释规则 5.1一般规则 程序中要保证20%的注释,边写程序边注释。不要吝啬注释。给以后需要理解你的代码的人们(或许就 是你自己)留下信息是非常有用的。注释应该和它们所注释的代码一样是书写良好且清晰明了。偶尔的小幽 默就更不错了。记得要避免冗长或者情绪化。 及时地更新注释也很重要。错误的注释会让程序更加难以阅读和理解。 让注释有意义。重点在解释那些不容易立即明白的逻辑上。不要把读者的时间浪费在阅读类似于: i=0;//让i等于0 使用单行注释。块注释用于注释正式文档和无用代码。 把注释看成程序的一部分,在编写/维护代码时同时编写/维护注释; 注释完全采用PHPDocumentor的规范,以方便用其生成API级文档。详细规则请参见PHPDocumentor手 册。 5.2方法/函数注释 方法声明时要在开头说明其实现功能、各参数、返回值意义,复杂逻辑要在声明时说明其实现思想,并 在关键步骤做出注释; 调用方法时也要指出其目的; 5.3类注释 类声明时要在头部注明类作用、作者、时间;修改时要注明修改人,修改说明;类头部的注释中要列出所 有的属性、方法,并指出其意义; 5.4记录所有的空语句 总是记录下for或者是while的空块语句,以便清楚的知道该段代码是漏掉了,还是故意不写的。 while($dest++=$src++);//VOID5.5用if(0)来注释外部代码块 有时需要注释大段的测试代码,最简单的方法就是使用if(0)块: functionexample(){ greatlookingcode if(0){ lotsofcode } morecode } 你不能使用/**/,因为注释内部不能包含注释,而大段的程序中可以包含注释。 5.6版权信息 //+—————————————————-+ //|phpDocumentor| //+—————————————————-+ //|Copyright(c)2000-2003JoshuaEichorn| //|Emailjeichorn@phpdoc.org| //|Webhttp://www.phpdoc.org| //+—————————————————-+ //|ThissourcefileissubjecttoPHPLicense| //+—————————————————-+ 备注使用//来标示版权信息,以免和PHPDocumentor的page-levelDocBlock发生冲突 -22-