前言：

对于 zentaoPHP 框架的开发，以及确保后续项目研发时团队成员编码能够统一，易企天创团队整理了该编码规范。本规范的核心规则就是驼峰方式的命名规则。此规范必要时可以打破。其他团队在实际研发过程中，不一定要严格遵守本规范，但建议团队中有自己的统一代码规范，本规范仅供参考。

一、PHP 命名规则

1.1 变量命名

采用驼峰方式。首字母小写，后面的字母按照大小写间隔的方式加以区分，比如userName, serviceID

• 如果有单词缩写，则采用大写形式。如：PID 。

• 应该避免大写的单词在一起，因为无法直接判断单词的分割，比如IMGFile，应该写成imgFile。

• 类名、类的属性命名规则与此相同。

• 数据库、表、字段的命名规则与此相同。

• SQL 查询语句中关键词使用大写。 比如：SELECT * FROM userList WHERE

1.2 常量命名

采用大写单词与下划线间隔的方式，比如IMATCH_DISPATCHER_API。

1.3 函数命名

• 采用驼峰方式，动词加名词，动词小写，后面的名词用大小写间隔。比如： getAdInfo()

• 如果需要，可以增加小写的前缀，这时动词则大写开始。比如： imGetAdInfo()

• 类的方法命名规则与此相同，不过类的方法一般不需要增加前缀了。

1.4 目录文件命名

• 目录和文件一般采用小写的格式，尽量使用两个以内的单词表达。

• 不建议使用下划线间隔的方式。但如果目录或者文件名过长，无法使用少量单词表达时，应当使用下划线。

• 不建议使用大写字母，但如果要表达的名称是大家约定俗称的，应尊重旧有的习惯。

二、PHP脚本文件的构成及注释

• 每个文件按照以下顺序排列：功能说明部分、包含声明部分、具体的业务逻辑、自定义函数部分。

• 注释按照phpdoc的标准进行，这样可以和c++程序统一起来。 http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.pkg.html

2.1 功能说明部分

在每一个文件的开头部分，要包含这个程序的简要说明、详细说明以及作者和最后修改时间。注释采用phpdoc的注释方式。

<?
/**
 * 监控程序（简单注释）
 *
 * 此脚本程序用来监控搜索所建索引的完整性、一致性、正确性。（详细说明，可选。）。
 * @author      wangcs <wwccss@263.net>
 * @version     $Id$
 */
?>

说明：

• 详细说明部分是可选的，如果某个文件的逻辑比较复杂，可以在详细说明部分加以解释。

• 其中的$Id$会被自动替换成subverion的相应信息，其中包含文件名、日期、修改者等信息。

2.2 包含声明部分：

在每个文档的开头部分包含此程序所用到的包含文件。如：

include 'init.php';
include 'func/common.php';

2.3 具体的业务逻辑

• 注释的原则是将问题解释清楚，并不是越多越好。

• 若干语句作为一个逻辑代码块，这个块的注释可以使用/* */方式。

• 具体到某一个语句的注释，可以使用行尾注释：// 或者#，但应当保持风格一致。

/* 生成配置文件、数据文件。*/
$this->setConfig();
$this->clearCache();        # 清除缓存文件。
$this->createDataFiles(); // 生成数据文件。

2.4 自定义函数部分

• 如果当前PHP脚本需要定义一个函数，则在文件尾部声明。

• 凡有两个以上文件用到的函数，应将其定义在一个公共的函数库文件中。比如function.php中。 

• 自定义函数需包含以下几个部分：函数功能描述、函数参数说明、返回值说明。示例：

<?
/**
  * 数据库连接函数（简单说明）
  *
  * 通过这个函数链接到数据库，并返回相信的链接标识符。(详细的说明)
  * @author                       wangcs<wwccss@263.net>
  * @global string             数据库服务器(全局变量声明,无需指定变量名，顺序对应)
 * @param string $SQL        连接成功以后执行的查询语句，默认为空。（变量声明）
  * @return array              返回数据库连接信息。（返回值说明）
  */
  function dbConnect ($SQL="")
  {
       global $mysql;
       xxxx;
       xxxx; 
  }
?>

• 如果函数功能比较简单，也可以采用一句话注释的方式，来说明此函数的作用，省略参数的说明。

<?php
/*清楚缓存文件（一句话说明，省略了参数的说明）*/
function clearCache()
{
if(!$this->clearCache) return;
Xxxxx;
}
?>

2.5 类的注释方式

<?php
/**
 * 测试的基本类文件。(类的基本说明)
 *
 * @author  chunsheng.wang 
 * @version $Id$
 */
/* xxx类。*/
class xxx
{
    var $binRoot;       # xxx运行的根目录。
    var $dataRoot;  # xxx数据文件所在的目录。
var $configFile; # xxx的配置文件。
    
/* 构造函数，初始化各个变量。*/
    function xxxx($clearCache = true)
    {
        /* 设置基本的参数。*/
        $this->binRoot  = $CFG['binRoot'];
        $this->dataRoot = $this->binRoot . 'data/';
    }
    ……
}

三、PHP书写格式约定

• 大括号分成两列书写，理由是可以方便的界定大括号的范围。

• 缩进采用四个空格，不使用Tab键进行缩进。

• 操作符前后应该有空格，比如 $userName = 'wangcs';

• 同一逻辑代码块的代码操作符应当尽量对齐，这样可以方便阅读与修改。

$userName     = 'wangcs';
$userAddress = 'hangzhou';

四、XHTML代码规范

4.1 样式表的引用

• 样式表通过外部引用的方式调用，不建议在页面中新定义样式。

• 页面元素中的展现形式不建议通过html代码进行定义，都统一使用样式表进行。

比如要显示红色字体，用Html代码可以这样进行定义：

<font clolor=”red”>红色字体</font>

但最好的方法是通过样式表来定义。

<span class=”redtext”>红色字段</span>

• 将对网站样式的定义集中到一个样式表文件中去，如果对网站进行修改，可以很快进行。而如果分散到各个网页文件中去，改动起来就非常麻烦了。

4.2 缩进、换行约定

• 网页代码的缩进使用两个空格。

因为网页嵌套标签可能比较多，所以使用四个空格进行缩进会导致最深层的代码缩进太多，因而使用两个空格进行缩进。

• 如果一行中代码太长，请换行。

<tr><td><input type=”text” name=”test” value=”test” class=”MyInput” onclick=”alert(‘test’)”></td></tr>

可以改成

<tr>
<td>
<input type=”text” name=”test” value=”test” class=”MyInput” onclick=”alert(‘test’)”>
</td>
</tr>

• 如果多行相似的代码出现，属性尽量对齐

<input type="hidden" name="ProjectID"    value="{$ProjectID}" />
<input type="hidden" name="ModuleID"     value="{$ModuleID}" />
<input type="hidden" name="BugID"         value="{$BugID}" />
<input type="hidden" name="AssignedTo"   value="{$AssignedTo}" />

type、name和value属性对齐以后阅读起来比较方便。

• 对于某种标记的多个属性，其顺序尽量保持一致。

比如table标记的定义可以按照下面的顺序来定义。

<table width="90%" align="center" border="0" cellpadding="1" cellspacing="0" class="BgTable">

4.3 书写规范

4.3.1 所有的标记都必须要有一个相应的结束标记

以前在HTML中，你可以打开许多标签，例如<p>和<li>而不一定写对应的</p>和</li>来关闭它们。但在XHTML中这是不合法的。XHTML要求有严谨的结构，所有标签必须关闭。如果是单独不成对的标签，在标签最后加一个"/"来关闭它。例如:<br /><img height="80" alt="网页设计师" src="../images/logo_w3cn_200x80.gif" width="200" />

4.3.2 所有标签的元素和属性的名字都必须使用小写

与HTML不一样，XHTML对大小写是敏感的，<title>和<TITLE>是不同的标签。XHTML要求所有的标签和属性的名字都必须使用小写。例如：<BODY>必须写成<body> 。大小写夹杂也是不被认可的，通常dreamweaver自动生成的属性名字"onMouseOver"也必须修改成"onmouseover"。

4.3.3 所有的标记都必须合理嵌套

4.3.4 所有的属性必须用引号""括起来

在HTML中，你可以不需要给属性值加引号，但是在XHTML中，它们必须被加引号。

4.3.5 给所有属性赋一个值

XHTML规定所有属性都必须有一个值，没有值的就重复本身。例如：

<td nowrap> <input type="checkbox" name="shirt" value="medium" checked>

必须修改为：

<td nowrap="nowrap"> 
<input type="checkbox" name="shirt" value="medium" checked="checked"> 
</td>

4.4 表单变量命名约定

表单中的变量命名采用PHP的命名方式，使用驼峰方式命名。比如：

<form name=”LoginForm”>
  <input type=”text”      name=”userName”  value=”” />
  <input type=”password” name=”password”   value=”” />
</form>

五、JavaScript 代码规范

5.1 变量命名约定

由于JavaScript区分大小写，所以对变量进行命名的时候需要谨慎。同时为了与php程序保持统一，JavaScript的变量命名也采用驼峰的形式。

5.2 函数命名、注释约定

5.2.1 函数命名采用动词+名词的形式，第一项首字母小写。也可以增加前缀。

比如：function checkUserName() 

增加前缀的命名可以为：function sysCheckUserName()

5.2.2 函数的注释沿用phpDoc的标准。

比如：

/**
 * Displays an confirmation box beforme to submit a "DROP/DELETE/ALTER" query.
 * This function is called while clicking links
 *
 * @author                         wangcs<wangcs@okooo.net>
 * @param   object   link        the link
 * @param   object   sqlQuery   the sql query to submit
 * @return  boolean              whether to run the query or not
 */
function confirmLink(link, sqlQuery)
{
}

5.3 代码书写规范

• 缩进约定：缩进采用四个空格进行缩进。

• 每一行都以”;”结束。

• 循环、逻辑判断中大括号都单独占一行。

• 相邻几行代码中相似的部分尽量对齐。 

比如：

/**
 * 动态显示表格。
 *
 * @author                    王春生 <wwccss@263.net>
 * @param  int id            表格编号。 
 * @param  int totalCount  表格总数。
 */
function showTable(id,totalCount)
{
    for (i = 1; i <= totalCount; i++)
    {
        if (I == ID)
        {
        }
        else
        {
        }
}
}

六、Git/SVN 操作约定

• php脚本开始部分应当加上$Id$标签，这样svn会自动将其替换为最后的修改时间、版本和修改者。

在提交svn的时候，需要通过下面的语句设置文件的Id属性：

svn propset svn:keywords Id

• commit的时候一定要写注释，注释的内容必须是此版本的修改信息。注释信息请按照下面的说明进行：

+ 表示新增功能 

* 表示修改功能

- 表示删除的功能；

• + - * 前后都有一个空格。