程序规范

2016-07-05 10:30:47
admin
1586
最后编辑:admin 于 2016-07-20 14:05:24

前言:

        本规范的目的是让保证team成员编码的统一。

        本规范的核心规则就是驼峰方式的命名规则。

        此规范必要时可以打破。

一、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包含声明部分:

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

 

i n c l u d e 'init.php';

i n c l u d e '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

        {

        }

}

}

六、Subverion操作约定:

       php脚本开始部分应当加上$Id$标签,这样svn会自动将其替换为最后的修改时间、版本和修改者。
在提交svn的时候,需要通过下面的语句设置文件的Id属性:
svn propset svn:keywords Id

       commit的时候一定要写注释,注释的内容必须是此版本的修改信息。注释信息请按照下面的说明进行:
+ 表示新增功能
*
表示修改功能
- 表示删除的功能;

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

发表评论
评论通过审核后显示。