定长discuz代码规范

Discuz!的编码规范

PHP编码规范与原则

书写规则

缩进

每个缩进的单位约定是一个TAB(4个空白字符宽度)需每个参与项目的开发人员在编辑器(Ultra Edit、EditP lus、ZendStudi o等)中进行强制设定 以防在编写代码时遗忘而造成格式上的不规范。

本缩进规范适用于PH P、 JavaS cript中的函数、类、逻辑结构、循环等。

大括号{}、 if和sw itch

 首括号与关键词同行尾括号与关键字同列

 if结构中else和elsei f与前后两个大括号同行左右各一个空格。另外即便if后只有一行语句仍然需要加入大括号 以保证结构清晰

 switc h结构中通常当一个case块处理后将跳过之后的case块处理 因此大多数情况下需要添加break。 break的位置视程序逻辑与case同在一行或新起一行均可但同一sw itch体中 break的位置格式应当保持一致。

以下是符合上述规范的例子if($condi tion) {switc h($var) {case 1: echo ‘var is 1’ ; break ;case 2: echo ‘var is 2’ ; break ;defau lt: echo ‘var is neith er 1 or 2’ ; break ;

}

} else {switch($str) {case ‘abc’ :

$resul t= ‘abc’ ;break ;defau lt:

$resul t= ‘unknown’ ;break ;

}

}

运算符、小括号、空格、关键词和函数

 每个运算符与两边参与运算的值或表达式中间要有一个空格唯一的特例是字符连接运算符号两边不加空格

 左括号“(”应和函数关键词紧贴在一起除此以外应当使用空格将“(”同前面内容分开

 右括号“)”除后面是“)”或者“.”以外其他一律用空格隔开它们

 除字符串中特意需要一般情况下在程序以及HTML中不出现两个连续的空格

 任何情况下 PH P程序中不能出现空白的带有TAB或空格的行 即这类空白行应当不包含任何TAB或空格。 同时任何程序行尾也不能出现多余的TAB或空格。多数编辑器具有自动去除行尾空格的功能如果习惯养成不好可临时使用它避免多余空格产生

 每段较大的程序体上、下应当加入空白行两个程序块之间只使用1个空行禁止使用多行。 程序块划分尽量合理过大或者过小的分割都会影响他人对代码的阅读和理解。一般可以以较大函数定义、逻辑结构、功能结构来进行划分。少于15行的程序块可不加上下空白行

 说明或显示部分中 内容如含有中文、数字、英文单词混杂应当在数字或者英文单词的前后加入空格。

根据上述原则 以下举例说明正确的书写格式

$resul t= ( ($a + 1) * 3 / 2 + $num) ) . ’ Test’ ;

$condi tion ?func1 ($var) : func2 ($var) ;

$condi tion ? $long_state ment : $anoth er_lo ng_st ateme nt;if($flag) {

//State ments

//More than 15 lines

}showm essag e( ‘请使用resto re.php工具恢复数据。 ’ ) ;

函数定义

 参数的名字和变量的命名规范一致

 函数定义中的左小括号与函数名紧挨 中间无需空格

 开始的左大括号与函数定义为同一行 中间加一个空格不要另起一行

 具有默认值的参数应该位于参数列表的后面

 函数调用与定义的时候参数与参数之间加入一个空格

 必须仔细检查并切实杜绝函数起始缩进位置与结束缩进位置不同的现象

例如符合标准的定义funct ionau thcod e($strin g, $opera tion, $key = ' ' ) {if($flag) {

//State ment

}

//函数体

}

不符合标准的定义funct ionau thcod e($strin g,$opera tion, $key = ' ' )

{

//函数体

}

引号

PHP中单引号和双引号具有不同的含义最大的几项区别如下

 单引号中任何变量($va r)、特殊转义字符(如“\t\r\n”等)不会被解析因此PH P的解析速度更快转义字符仅仅支持“\’”和“\\”这样对单引号和反斜杠本身的转义

 双引号中变量($va r)值会代入字符串中特殊转义字符也会被解析成特定的单个字符还有一些专门针对上述两项特性的特殊功能性转义例如“\$”和“{$array[ ‘key’ ]}。这样虽然程序编写更加方便但同时PH P的解析也很慢

 数组中如果下标不是整型而是字符串类型请务必用单引号将下标括起正确的写法为$a rra y[ ‘key’ ] 而不是$array[key] 因为不正确的写法会使PHP解析器认为ke y是一个常量进而先判断常量是否存在不存在时才以“key”作为下标带入表达式中 同时出发错误事件产生一条N otice级错误。 因此在绝大多数可以使用单引号的场合禁止使用双引号。依据上述分析可以或必须使用单引号的情况包括但不限于下述o 字符串为固定值不包含“\t”等特殊转义字符o 数组的固定下标例如$array[ ‘key’ ] o 表达式中不需要带入变量例如$strin g= ‘test’ ; 而非$strin g= “test$var”

 例外的在正则表达式(用于pre g_系列函数和ere g系列函数)中 Discu z!全部使用双引号这是为了人工分析和编写的方便并保持正则表达式的统一减少不必要的分析混淆。

 数据库SQ L语句中所有数据必须加单引号无论数值还是字串 以避免可能的注入漏洞和SQL错误。正确的写法为

UPDAT E cdb_m ember s SET admin id=’ 1’ WHERE usern ame=’ $admin’ AND admin id=’ 2’ ;

所有数据在插入数据库之前均需要进行addsl ashes ()处理 以免特殊字符未经转义在插入数据库的时候出现错误。 Discu z!中所有通过GET, POST, FI LE,取得的变量默认情况下已经使用了addsl ashes ()进行了转义不必重复进行。如果数据处理必要(例如用于直接显示) 可以使用s trips lashe s()恢复但数据在插入数据库之前必须再次进行转义。缓存文件中一般对缓存数据的值采用addc slash es($strin g, '\'\\')进行转义。

变量的初始化与逻辑检查

任何变量在进行累加、直接显示或存储前必需进行初使化,例如

$numbe r= 0; //数值型初始化

$string= ‘ ’ ; //字符串初始化

$array = array () ; //数组初始化

 判断一个无法确定不知道是否已被赋值的变量时可用empty()或isse t()而不要直接使用if($switc h)的形式除非你确切的知道此变量一定已经被初始化并赋值。empty()和isse t()的区别为

 bool empty(mixed var)

如果var是非空或非零的值则empty()返回FALSE 。换句话说 ""、 0、 "0"、 NULL、 FALSE 、 array()、 var$var;以及没有任何属性的对象都将被认为是空的如果var为空则返回TRUE。

 booli sset(mixed var[,mixed var[, ...]])

 如果var存在则返回 TRUE否则返回FALSE 。

 如果已经使用unset ()释放了一个变量之后它将不再是isset ()。若使用is set()测试一个被设置成NULL的变量将返回FALSE。 同时要注意的是一个NULL字节"\0"并不等同于 PHP的NULL常数。

 判断一个变量是否为数组请使用is_arra y()这种判断尤其适用于对数组进行遍历的操作例如for each() 因为如果不事先判断 forea ch()会对非数组类型的变量报错

 判断一个数组元素是否存在可使用is set($array[ ‘key’ ]) 也可使用e mpty()两者异同见上。

代码重用

 在需要多次使用代码并且对于您希望实现的任务没有可用的内置PHP函数时不吝啬定义函数或类。开发者须根据功能、调用情况将函数和类放置于相应的func tion或class中。超过3行实现相同功能的程序切勿在不同程序中多次出现这是无法容忍和回避的问题

 在任何时候都不要出现同一个程序中出现两段或更多的相似代码或相同代码 即便在不同程序中也应尽力避免。开发者应当总是有能力找到避免代码大段(超过10行重)复或类似的情况。

包含调用

 包含调用程序文件请全部使用requi re_once 以避免可能的重复包含问题

 包含调用缓存文件 由于缓存文件无法保证100%正确打开请使用in clude_once或incl ude。在必要时可以使用@inclu de_on ce或@include的方式 以忽略错误提示

 包含和调用代码中须以“./”或DISCUZ_ROOT. ’ ./’开头应避免直接写程序文件名(例如 requi re_once ‘x.php’ ;)的做法

 所有被包含和调用的程序文件包括但不限于程序、缓存或模板通常其不能被直接UR L请求。 Discuz!通过在./sourc e/class/class_core.php中定义一个标记性常量IN_DISC UZ来判断程序是否被合法调用。因此在除了./sourc e/class/class_core.php以外的任何一个被包含和调用的程序文件中需要包含以下内容 以使得访问者无法直接通过URL请求该文件if(!defined(' IN_DISCUZ' ) ) {exit('Acces sDenied' ) ;

}

错误报告级别

 在软件开发和调试阶段请使用er ror_r eport ing(E_ALL);作为默认的错误报告级别此级别最为严格能够报告程序中所有的错误、警告和提示信息 以帮助开发者检查和核对代码避免大多数安全性问题和逻辑错误、拼写错误。 error_repo rting()可以在co nfig/confi g_glo bal.php中添加一行$_conf ig['debug']=1;debug值可以在0~2之前取值数值越大报错等级越高。

 在软件发布时请使用er ror_r eport ing(E_ERR OR| E_WAR NING| E_PAR SE);作为默认的错误报告级别 以利于用户使用并将无谓错误提示信息降至最低。

数据库设计

表和字段命名

所有数据表名称只要其名称是可数名词则必须以复数方式命名例如 cdb_m ember s(用户表)、 cdb_p osts(帖子表)存储多项内容的字段或代表数量的字段也应当以复数方式命名例如 param s(param eters  自定义Di scuz!代码的参数个数)、 views (查看次数)、 repl i es(回复次数)。

 任何类型的数据表字段空间应当本着足够用不浪费的原则数值类型的字段取值范围见下表

SQL语句

 所有SQL语句中除了表名、字段名称以外全部语句和函数均需大写应当杜绝小写方式或大小写混杂的写法。例如sel ect*from cdb_m ember s;是不符合规范的写法。

 很长的SQL语句应当有适当的断行依据JOI N、 FROM、 ORDER BY等关键字进行界定。

 通常情况下在对多表进行操作时要根据不同表名称对每个表指定一个1~2个字母的缩写 以利于语句简洁和可读性。

如下的语句范例是符合规范的

$query = $db->query ("SELEC T s.*, m.* FROM {$table pre}sessi ons s, {$table pre}membe rs m WHEREm.uid=s.uid AND s. sid=' $sid' ) ;

性能与效率

定长与变长表(discus_表名红色部分为定长表)

包含任何v archa r、 text等变长字段的数据表 即为变长表反之则为定长表。

 对于变长表 由于记录大小不同在其上进行许多删除和更改将会使表中的碎片更多。需要定期运行OPTI MIZE TABLE以保持性能。而定长表就没有这个问题

 如果表中有可变长的字段将它们转换为定长字段能够改进性能 因为定长记录易于处理。但在试图这样做之前应该考虑下列问题

 使用定长列涉及某种折衷。它们更快但占用的空间更多。 char(n)类型列的每个值总要占用n个字节(即使空串也是如此) 因为在表中存储时值的长度不够将在右边补空格

 而varc har(n)类型的列所占空间较少 因为只给它们分配存储每个值所需要的空间每个值再加一个字节用于记录其长度。因此如果在ch ar和va rchar类型之间进行选择需要对时间与空间作出折衷 变长表到定长表的转换不能只转换一个可变长字段必须对它们全部进行转换。而且必须使用一个ALTERTABLE语句同时全部转换否则转换将不起作用

 有时不能使用定长类型 即使想这样做也不行。例如对于比255字符更长的串没有定长类型 在设计表结构时如果能够使用定长数据类型尽量用定长的 因为定长表的查询、检索、更新速度都很快。必要时可以把部分关键的、承担频繁访问的表拆分例如定长数据一个表非定长数据一个表。例如Dis cuz!的cdb_membe rs和cd b_mem berfi elds表、cdb_f orums和cdb_forum field s表等。因此规划数据结构时需要进行全局考虑

进行表结构设计时应当做到恰到好处反复推敲从而实现最优的数据存储体系。

运算与检索

 数值运算一般比字符串运算更快。例如比较运算可在单一运算中对数进行比较。而串运算涉及几个

逐字节的比较如果串更长的话这种比较还要多。

 如果串列的值数目有限应该利用普通整型或e mum类型来获得数值运算的优越性。

 更小的字段类型永远比更大的字段类型处理要快得多。对于字符串其处理时间与串长度直接相关。

一般情况下较小的表处理更快。对于定长表应该选择最小的类型只要能存储所需范围的值即可。

例如如果med iumint够用就不要选择bigint。对于可变长类型也仍然能够节省空间。一个TEXT类

型的值用2字节记录值的长度而一个LO NGTEX T则用4字节记录其值的长度。如果存储的值长度永远

不会超过64KB使用TEXT将使每个值节省2字节。

结构优化与索引优化

索引能加快查询速度而索引优化和查询优化是相辅相成的既可以依据查询对索引进行优化也可以依据现有索引对查询进行优化这取决于修改查询或索引哪个对现有产品架构和效率的影响最小。

索引优化与查询优化是多年经验积累的结晶在此无法详述但仍然给出几条最基本的准则。

首先根据产品的实际运行和被访问情况找出哪些SQL语句是最常被执行的。最常被执行和最常出现在程序中是完全不同的概念。最常被执行的SQL语句又可被划分为对大表(数据条目多的)和对小表(数据条目少的)的操作。无论大表或小表有可分为读(SELEC T)多、写(UPDAT E/INSER T)多或读写都多的操作。

对常被执行的SQL语句而言对大表操作需要尤其注意

 写操作多的通常可使用写入缓存的方法先将需要写或需要更新的数据缓存至文件或其他表定期

对大表进行批量写操作例如Dis cuz!中点击数延迟更新机制就是依据此原理实现。 同时应尽量使

得常被读写的大表为定长类型 即便原本的结构中大表并非定长。大表定长化可以通过改变数据存

储结构和数据读取方式将一个大表拆成一个读写多的定长表和一个读多写少的变长表来实现

 读操作多的需要依据SQL查询频率设置专门针对高频SQL语句的索引和联合索引。

而小表就相对简单加入符合查询要求的特定索引通常效果比较明显。 同时定长化小表也有益于效率和负载能力的提高。字段比较少的小定长表甚至可以不需要索引。

其次看SQL语句的条件和排序字段是否动态性很高(即根据不同功能开关或属性 SQL查询条件和排序字段的变化很大的情况)动态性过高的SQL语句是无法通过索引进行优化的。惟一的办法只有将数据缓存起来定期更新适用于结果对实效性要求不高的场合。

MySQL索引常用的有P RIMAR YKEY、 INDEX、UNIQU E几种详情请查阅MySQL文档。通常在单表数据值不重复的情况下 PRIMA RY KEY和U NIQUE索引比IN DEX更快请酌情使用。

事实上索引是将条件查询、排序的读操作资源消耗分布到了写操作中索引越多耗费磁盘空间越大写操作越慢。因此索引决不能盲目添加。对字段索引与否最根本的出发点依次仍然是SQL语句执行的概率、表的大小和写操作的频繁程度。

查询优化

MySQL 中并没有提供针对查询条件的优化功能 因此需要开发者在程序中对查询条件的先后顺序人工进行优化。例如如下的SQL语句

SELEC T* FROM table WHERE a>’ 0’ AND b<’ 1’ ORDER BY c LIMIT 10;

事实上无论a>’ 0’还是b<’ 1’哪个条件在前得到的结果都是一样的但查询速度就大不相同尤其在对大表进行操作时。

开发者需要牢记这个原则最先出现的条件一定是过滤和排除掉更多结果的条件第二出现的次之 以此

类推。因而表中不同字段的值的分布对查询速度有着很大影响。而OR D E R BY中的条件只与索引有关与条件顺序无关。

除了条件顺序优化以外针对固定或相对固定的SQL查询语句还可以通过对索引结构进行优化进而实现相当高的查询速度。原则是在大多数情况下根据WHE RE条件的先后顺序和ORDER BY的排序字段的先后顺序而建立的联合索引就是与这条SQL语句匹配的最优索引结构。尽管事实的产品中不能只考虑一条SQ L语句也不能不考虑空间占用而建立太多的索引。

同样以上面的SQL语句为例最优的当t able表的记录达到百万甚至千万级后可以明显的看到索引优化带来的速度提升。

依据上面条件优化和索引优化的两个原则 当tabl e表的值为如下方案时可以得出最优的条件顺序方案

EXPLA IN语句是检测索引和查询能否良好匹配的简便方法。在phpM yAdmi n或其他M ySQL客户端中运行EXPLAIN+查询语句例如EXPLAINSELECT* FROMtable WHERE a>’ 0’ ANDb<’ 1’ ORDER BYc;这种形式 即使得开发者无需模拟上百万条数据也可以验证索引是否合理相关细节请参考MyS QL说明。

值得提出的是Using fi les ort是最不应当出现的情况如果EXP LAIN得出此结果说明数据库为这个查询专门建立了一个用以缓存结果的临时表文件并在查询结束后删除。众所周知硬盘I/O速度始终是计算机存储的瓶颈 因此查询中应当尽全力避免高执行频率的SQL语句使用fi lesor t。尽管开发者永远都不可能保证产品中的全部SQL语句都不会使用fi l esort 。

限于篇幅本文档远远没有涵盖数据库优化的方方面面例如联合索引与普通索引的可重用性、 JOIN连接的索引设计、MEMORY/HEAP表等。数据库优化实际上就是在很多因素和利弊间不断权衡、修改惟有在成功与失败经验中反复推敲才能得出的经验这种经验往往就是最难能可贵和价值连城的。

模板设计

代码标记

<!--{hook/forum display_fastpost_content}-->

HTML代码标记一律采用小写字母形式杜绝任何使用大写字母的方式

模板中所有的逻辑体如{if}、 {loop}等必须前后使用HTML注释() 即类似的形式。事实上 Discu z!模板编译器是支持不加HTML注释的逻辑体写法的但加入注释可以使得模板可读性更好 同时方便用户使用Dr eamWeaver或Front Page等对模板进行修改。

在HTML标记中使用的逻辑体无需使用HT ML注释()  即<input type=” text” {if xxx}value =” 1” {/if}/>文件与目录

文件命名

所有包含P HP代码的程序文件或半程序文件应以小写.php作为扩展名而不要使用.phtml 、 .php3、 . inc、 .class等作为扩展名。

普通程序

能够被UR L直接调用的程序例如hom e.php、 index.php、 forum.php直接使用程序名+.php的方式命名函数库和类库程序

分别以小写funct ion_x xxx.php和c lass_xxxx.php的格式命名书写。函数库和类库程序只能被其他程序引用而不能独立运行。其中不能包含任何流程性的、不属于任何函数或类的程序代码。

流程性程序插件时常用到

以小写. inc.php作为扩展名。只能被其他程序引用而不能独立运行。其中不能包含任何函数或类代码的程序代码。

模板源文件

以小写.htm作为扩展名。模板源文件按照Dis cuz!模板编码规则进行编写不是可以执行的程序而只能被Discuz模!板编译器所解析放置于./templ ates/defau lt或./templ ates下的其他模板目录下。

模板目标文件

模板文件被编译后自动生成的目标程序 以小写.tpl .php作为扩展名存放于./data/templ ate目录下。语言包文件

 以小写la ng_xx xx.php格式命名只能存放模板或程序使用的语言包信息。

 模板语言包存放在对应模块名下的lang_templ ate.php例如家园的模板语言包so urce\language\home\lang_templ ate.php

缓存文件

此类文件为系统自动生成 以cach e_xxx .php、 userg roup_ xxx.php、 style _xxx.php等类似形式命名 存放于./data/cache目录下。