代码规范

2021-09-27 10:56:16
admin
2787
最后编辑:admin 于 2021-09-28 13:42:56

前言:

对于 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的时候一定要写注释,注释的内容必须是此版本的修改信息。注释信息请按照下面的说明进行:

+ 表示新增功能 

* 表示修改功能

- 表示删除的功能;

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