PHP编码规范文档

最后更新于:2022-04-01 11:54:25

      为了提高工作效率,保证开发的有效性和合理性,并最大程度提高程序代码的可读性和可重复利用性,提高沟通效率,需要一份代码编写规范。让大家养成良好的代码编写习惯,同时减少代码中的bug。       CleverCode整理了一些规范。本规范包含PHP开发时程序编码中命名规范、代码缩进规则、控制结构、函数调用、函数定义、注释、包含代码、PHP标记、常最命名等方面的规则。 ## 1 文件格式 ### 1.1 文件标记 所有PHP文件,其代码标记均使用完整PHP标签,不建议使用短标签,例如: ~~~ <?php //推荐 echo 'hello world'; ?> <? //短标签格式不推荐 echo ' hello world '; ?> ~~~ 1) 使用短标签格式容易和XML混淆,并且不是所有PHP版本和服务器都默认支持或打开短标签选项(从PHP5.4开始,php.ini中的短标签选项不影响短标签的使用)。对于只含有PHP代码的文件,将在文件结尾处忽略?>。这是为了防止多余空格或者其他字符影响到代码。 2)实际上这个问题只有在不开启压缩或缓存输出时才会出现,例如: php.ini-禁止压缩输出及缓存输出 zlib.output_conpression = off output_buffering = off foo.php,注意这个时候有一些空格或换行符掉在了之后,当然这在页面上是看不 到的。 ~~~ <?php $foo= 'foo'; ?> ~~~ index.php,在包含foo.php的同时,实际上已经输出一些空格或换行了。 ~~~ <?php include 'foo.php'; session_start(); ?> ~~~ 这时将看到一个警告(warning):“...Cannotsendsessioncachelimiter-headersalreadysent...” ### 1.2 文件和目录命名 程序文件名和目录名均采用有意义的英文命名,不使用拼音或无意义的字母,只允许出现字母、数字、下画线和中画线字符,同时必须以“.php”结尾(模板文件除外)。 //类统一采用 DemoTest.php ## 2 命名规范 ### 2.1 变量命名 PHP中的变量用一个美元符号后面跟变量名表示。变量名区分大小写。一个有效变景名由字母或者下画线开头,后面跟任意数量的字母、数字、下画线。正常的正则表达式将表述为:[a-zA-Z_\x7f-\xff][a-zA-ZO-9_'x7f-\xff],不应该在变量中使用中文等非ASCII字符。 ### 2.1.1 程序整体 程序整体以驼峰法命名,以小写字母开始,同时命名要有意义,如: ~~~ function displayName($name){ echo $name; } ~~~ ### 2.1.2 PHP全局变量键值 PHP全局变量键值两边都有中间使用驼峰法命名。 ### 2.1.3 普通变量 普通变量整体采用驼峰法, 按照约定命名,并避免使用常用关键字或存在模糊意义的单词。变量应该以名词为主。 字符串:$myName 数组:$myArray 不推荐: $yes:不应该使用其作为bool型变童,因为变量很可能被改变,其可能使得Syeszflase,而让其代码逻辑变得混乱。 $sex:具有模糊意义且不地道的英文单词,性别的命名应该是$gender。 ### 2.1.4 函数名 函数名既要有意义,一看就知道要干什么,也要尽量缩写。建议采用动词或动词加形容词 的命名方式,如showMsg。不建议下面这样的函数名:getPublishedAdvertisementBy CategoryAndCategoryldAndPosition() 上面的函数名可以提炼为:getAd($category,$categoryid,$position,$published) 例如1)类公共函数: public function doGetUserName($job) 例如2)类私有函数,以“_”开头: private function _doGetUserName($job) 例如3)类保护函数,以“_”开头: protected function _doGetUserName($job) ### 2.1.5 类中的属性 类中的变量遵守普通变量的命名规则。 例如1)公共属性,static属性: public $userName = ’CleverCode’; static $userType = array(1,2,3); 例如2)私有属性,以“_”开头: private $_userName = ’CleverCode’; 例如3)保护属性,以“_”开头: protected $_userName = ’CleverCode’; 例如4)常量,全部大写,以“_”分隔: const TYPE_GZ = 4; ### 2.2 数据库命名 ### 2.2.1 库命名 1)使用小写字母。(windows不区分大小写,linux区分大小写,为了库移植兼容,所以全部小写) 2)多个单词组成,单词之间用"_"分隔。 例如:db_user,db_system。 ### 2.2.2 表命名 1)表名均使用小写字母。 2)表名字使用统一的前缀,且前缀不能为空(模块化,且可有效规避MYSQL保留字)。 3)对于多个单词组成的表名,使用"_"间隔。 例如: pre_users,pre_user_shop ### 2.2.3 表字段命名 1)全部使用小写字母命名。 2)多个单词不用下画线进行分割(重要)。 3)如果有必要,给常用字段加上表名首字母作为前缀。 4)避免使用关键字和保留字,但约定俗成的除外。 例如: username,newsid,userid,logid ## 3 注释规范 ### 3.1 文件注释 文件注释通常放在整个PHP文件头部,其内容包括文件版权、作者、编写日期、版本号等 重要信息。PHP中,可以参照phpdocument规范,便于利用程序自动生成文档。 文件注释遵循以下规则: 1)必须包含本程序的描述; 2)必须包含作者; 3)必须包含版权; 4)必须包含文件的名称; 5)可以包含书写日期; 6)可以包含版本信息; 7)可以包含重要的使用说明,如类的调用方法、注意事项等。 例如: ~~~ <?php /** * SystemUser.php * * 系统用户操作操作 * * Copyright (c) 2015 http://blog.csdn.net/CleverCode * * modification history: * -------------------- * 2015/5/11, by Clever Code, Create * ~~~ ### 3.2 类与接口注释 类和接口的注释应该尽量简洁。按照一般的习惯,一个文件只包含一个类,在类注释中通常不需要再加上作者和版本等信息,加上可见性和简中的描述即可。如果文件注释已经足够详细,可以不用给类写注释。如果同时存在接口和接口的实现类,通常做法是仅在接口中进行注释。 ### 3.3 方法和函数注释 方法和函数的注释写在前面,通常需要标明的信息主要是可见性、参数类型和返回值的类 例如1: ~~~ /** * 对比新旧数据 * * @param bigint $userid 人编号 * @param array $oldMap 旧数据 * @param array $newMap 新数据(输出参数) * @return string 成功返回'OK',失败返回错误信息 */ public static function diffRecommendInfo($userid, $oldMap, &$newMap){ } ~~~ 例如2: ~~~ /** * 插入日志数据 * * @param bigint $data[‘userid’] 用户编号 * @param array $data[‘logintime’] 登录时间 * @return string 成功返回'OK',失败返回错误信息 */ public static function insertLogData($data){ } ~~~ ### 3.4 Action注释 由于我们都是使用的zend开发模式,在Action是http请求处理逻辑的入口,那么必然会传递get,post等参数。可以注释如下. 例如1)没有get,post传递参数时候: ~~~ /** * 自动设置名称 * * @return void */ public function autosetAction(){ } ~~~ 例如2 )有get传递参数时候: ~~~ /** * 获取用户名称 * * @get int $userid 用户编号 * @get int $currpage 当前页 * @get int $pagesize * * @return void */ public function getusernameAction(){ } ~~~ 例如3) 有post传递参数时候: ~~~ /** * 删除用户 * * @post int $userid 用户编号 * @return void */ public function deleteuserAction(){ } ~~~ ### 3.5 单行注释 1)写在被注释代码前面,而不是后面。但对于单行语句,按照习惯可以把注释放在语句末尾,也可以写在行上面。 2)对于大段注释,使用/**/格式,通常在文件和函数注释中使用,而代码内部统一使用//注释,因为其写起来简单。 例如: //姓名 $name = ’CleverCode’; ## 4 代码风格 ### 4.1 缩进与空格 在书写代码的时候,必须注意代码的缩进规则: 1)使用4个空格作为缩进,而不使用tab缩进(如在UltraEdit中可以进行预先设置)。 2)变量赋值时,等号左右留出空格。 例如: $name = 'CleverCode';//推荐 $name='CleverCode';//不推荐 为了最大程度减轻工作量,保持代码美观,建议使用大型IDE管理代码。比如,在zend studio中,使用Ctrl+Shift+F组合键对代码进行格式化。 ### 4.2 语句断行 代码书写中应遵循以下原则: 1)尽量保证程序语句一行就是一句; 2)尽量不要使一行的代码太长,一般控制在80个字符以内; 如果一行代码太长,请使用类似.=的方式断行书写; 执行数据库的SQL语句操作时,尽量不要在函数内写SQL语句,而先用变量定义SQL 语句,然后在执行操作的函数中调用定义的变量。 例如: //代码分割 $sql= "SELECTusername,password,address,age,postcode from test_t"; $sql.= "WHEREusername=${user}"; $ret = mysql_query($sql); 3)一个函数控制在200行以内; 4)if最多嵌套3层; //不推荐 ~~~ If(){ If(){ If(){ If(){ …… } } } } ~~~ 5)循环最多3层。 ~~~ //不推荐 For(){ For(){ For(){ For(){ …… } } } } ~~~ 6)if或者for语句块中只有一行时候,加上{}。当有语句变动的时候会带来不必要的bug。 ~~~ //推荐 If($a == 1){ echo 1; } //不推荐 If($a == 1) echo 1; ~~~ ### 4.3 空行 1)函数与函数之间空行。 2)同一个函数不同逻辑块之间空行,查阅不同的逻辑块条理更清晰。 ### 4.4 函数结构 通常一个函数分为三部分。第一部分:检查参数;第二部分:处理逻辑;第三部分:返回结果。 例如: ~~~ /** * 删除日志通过uid * * @param string $uid 用户uid * @return string 成功返回'OK',失败返回错误信息 */ public static function deleteLogByUid($uid){ //第一步:检查参数。防止处理部分异常;比如$uid是传入array(); if (!is_numeric($uid)) { return '!is_numeric($uid)'; } //第二步:处理逻辑。 $affected = $userLogTable->delete('where userid = ' . $uid); //第三步:返回结果。让调用者知道是否处理正常。 if($affected){ return 'OK'; } return 'delete error!'; } ~~~ ### 4.5 函数返回函数 需要客户端的函数: 返回值 $ret = array(‘code’=> 1 ,msg=>’’,data => array()); ### 4.6 更好的习惯 在代码中,使用下面列举的写法,可以使代码更优雅。 1)多使用PHP中已经存在的常量,而不要自己定义,例如: echo$meg."\r\n"; echo$msg,PHPJEOL; PHP中,PHP_EOL是一个预定义常量,表示一行结束,随着所使用系统的不同,使用PHP_EOL会让代码更具有可移植性。 2)更详尽的注释。 注释是一门艺术,好的注释可以比代码更精彩。不用担心效率问题。一则注释对代码的效 率影响不大,其次在正式产品中可以对代码中的注释进行批量删除。注释做到极致和完美的典型代表是Apache组织各种产品的源代码。 3)不要滥用语法糖。 语法糖也就是语言中的潜规则,即不具有普遍代表性的语法。少量使用语法糖会尝到甜 头,大量使用则是一种灾难。 例如以下代码,可读性比较差; $a?$a-$b:3&&$c&&$d=1; ![](https://docs.gechiui.com/gc-content/uploads/sites/kancloud/2016-03-29_56fa2a0c7acf5.jpg)
';