- 1 认识 zentaoPHP 框架
- 2 入口文件
- 3 配置管理
- 4 模块管理
- 4.1 控制器(control)
- 4.2 业务逻辑(model)
- 4.2.1 定义 model
- 4.2.2 跨模块调用
- 4.2.3 获取模块名
- 4.2.4 删除记录
- 4.2.5 数据处理对象 dao
- 4.3 模版视图(view)
- 4.4 从 hello world 开始
- 4.5 模块的配置
- 4.6 模块的语言
- 4.7 模块的 CSS 和 JS 管理
- 5 类库
- 6 扩展机制
- 6.1 扩展机制简介
- 6.2 新增独立模块
- 6.3 对控制层(control)扩展
- 6.4 对模型层(model)扩展
- 6.5 对视图层(view)扩展
- 6.6 对样式表和js进行扩展
- 6.7 对语言配置进行扩展
代码规范
- 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的时候一定要写注释,注释的内容必须是此版本的修改信息。注释信息请按照下面的说明进行:
+ 表示新增功能
* 表示修改功能
- 表示删除的功能;
+ - * 前后都有一个空格。