PHP编码规范文档

      为了提高工作效率，保证开发的有效性和合理性，并最大程度提高程序代码的可读性和可重复利用性，提高沟通效率，需要一份代码编写规范。让大家养成良好的代码编写习惯，同时减少代码中的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;

 

技术交流

CleverCode是一名架构师，技术交流，咨询问题，请加CleverCode创建的qq群(架构师俱乐部)：517133582。加群和腾讯，阿里，百度，新浪等公司的架构师交流。【架构师俱乐部】宗旨：帮助你成长为架构师！