超全的最新技术开发必备之--DiscuzX3技术开发文档

1Discuz技术开发文档一、Discuz!的编码规范前言本规范由编程原则组成，融合并提炼了开发人员长时间积累下来的成熟经验，意在帮助形成良好一致的编程风格。适用范围如无特殊说明，以下规则要求完全适用于Discuz!项目，同时也可大部分适用于COMSENZ旗下其他PHP项目。标准化的重要性和好处当一个软件项目尝试着遵守公共一致的标准时，可以使参与项目的开发人员更容易了解项目中的代码、弄清程序的状况。使新的参与者可以很快的适应环境，防止部分参与者出于节省时间的需要，自创一套风格并养成终生的习惯，导致其它人在阅读时浪费过多的时间和精力。而且在一致的环境下，也可以减少编码出错的机会。缺陷是由于每个人的标准不同，所以需要一段时间来适应和改变自己的编码风格，暂时性的降底了工作效率。从使项目长远健康的发展以及后期更高的团队工作效率来考虑暂时的工作效率降低是值得的，也是必须要经过的一个过程。标准不是项目成功的关键，但可以帮助我们在团队协作中有更高的效率并且更加顺利的完成既定的任务。程序员可以了解任何代码，弄清程序的状况新人可以很快的适应环境防止新接触PHP的人出于节省时间的需要，自创一套风格并养成终生的习惯防止新接触PHP的人一次次的犯同样的错误在一致的环境下，人们可以减少犯错的机会程序员们有了一致的敌人PHP编码规范与原则代码标记PHP程序可以使用?php?来界定PHP代码，在HTML页面中嵌入纯变量时，可以使用?phpecho$variablename;?这样的形式。注意：为了使代码进一步规范化和标准化，从Discuz!2X2版本起开始禁用??和?=$variablename?这种速记形式。注释注释是对于那些容易忘记作用的代码添加简短的介绍性内容。请使用C样式的注释“/**/”和标准C++注释“//”。在Discuz!每一个程序文件头部中，应放入相应SVN控制字串，以方便SVN提交时自动更新：$Id$例如：/***[Discuz!](C)2001-2099ComsenzInc.*ThisisNOTafreeware,useissubjecttolicenseterms**$Id$*/程序开发中难免留下一些临时代码和调试代码，此类代码必须添加注释，以免日后遗忘。所有临时性、调试性、试验性的代码，必须添加统一的注释标记“//debug”并后跟完整的注释信息，这样可以方便在程序发布和最终调试前批量检查程序中是否还存在有疑问的代码。例如：$num=1;$flag=TRUE;//debug这里不能确定是否需要对$flag进行赋值if(empty($flag)){//Statements}书写规则缩进每个缩进的单位约定是一个TAB(4个空白字符宽度)，需每个参与项目的开发人员在编辑器(UltraEdit、EditPlus、ZendStudio等)中进行强制设定，以防在编写代码时遗忘而造成格式上的不规范。本缩进规范适用于PHP、JavaScript中的函数、类、逻辑结构、循环等。大括号{}、if和switch首括号与关键词同行，尾括号与关键字同列；3if结构中，else和elseif与前后两个大括号同行，左右各一个空格。另外，即便if后只有一行语句，仍然需要加入大括号，以保证结构清晰；switch结构中，通常当一个case块处理后，将跳过之后的case块处理，因此大多数情况下需要添加break。break的位置视程序逻辑，与case同在一行，或新起一行均可，但同一switch体中，break的位置格式应当保持一致。以下是符合上述规范的例子：if($condition){switch($var){case1:echo‘varis1’;break;case2:echo‘varis2’;break;default:echo‘varisneither1or2’;break;}}else{switch($str){case‘abc’:$result=‘abc’;break;default:$result=‘unknown’;break;}}运算符、小括号、空格、关键词和函数每个运算符与两边参与运算的值或表达式中间要有一个空格，唯一的特例是字符连接运算符号两边不加空格；左括号“(”应和函数关键词紧贴在一起，除此以外应当使用空格将“(”同前面内容分开；右括号“)”除后面是“)”或者“.”以外，其他一律用空格隔开它们；除字符串中特意需要，一般情况下，在程序以及HTML中不出现两个连续的空格；任何情况下，PHP程序中不能出现空白的带有TAB或空格的行，即：这类空白行应当不包含任何TAB或空格。同时，任何程序行尾也不能出现多余的TAB或空格。多数编辑器具有自动去除行尾空格的功能，如果习惯养成不好，可临时使用它，避免多余空格产生；4每段较大的程序体，上、下应当加入空白行，两个程序块之间只使用1个空行，禁止使用多行。程序块划分尽量合理，过大或者过小的分割都会影响他人对代码的阅读和理解。一般可以以较大函数定义、逻辑结构、功能结构来进行划分。少于15行的程序块，可不加上下空白行；说明或显示部分中，内容如含有中文、数字、英文单词混杂，应当在数字或者英文单词的前后加入空格。根据上述原则，以下举例说明正确的书写格式：$result=(($a+1)*3/2+$num)).’Test’;$condition?func1($var):func2($var);$condition?$long_statement:$another_long_statement;if($flag){//Statements//Morethan15lines}showmessage(‘请使用restore.php工具恢复数据。’);函数定义参数的名字和变量的命名规范一致；函数定义中的左小括号，与函数名紧挨，中间无需空格；开始的左大括号与函数定义为同一行，中间加一个空格，不要另起一行；具有默认值的参数应该位于参数列表的后面；函数调用与定义的时候参数与参数之间加入一个空格；必须仔细检查并切实杜绝函数起始缩进位置与结束缩进位置不同的现象；例如，符合标准的定义：functionauthcode($string,$operation,$key=''){if($flag){//Statement}//函数体5}不符合标准的定义：functionauthcode($string,$operation,$key=''){//函数体}引号PHP中单引号和双引号具有不同的含义，最大的几项区别如下：单引号中，任何变量($var)、特殊转义字符(如“\t\r\n”等)不会被解析，因此PHP的解析速度更快，转义字符仅仅支持“\’”和“\\”这样对单引号和反斜杠本身的转义；双引号中，变量($var)值会代入字符串中，特殊转义字符也会被解析成特定的单个字符，还有一些专门针对上述两项特性的特殊功能性转义，例如“\$”和“{$array[‘key’]}。这样虽然程序编写更加方便，但同时PHP的解析也很慢；数组中，如果下标不是整型，而是字符串类型，请务必用单引号将下标括起，正确的写法为$array[‘key’]，而不是$array[key]，因为不正确的写法会使PHP解析器认为key是一个常量，进而先判断常量是否存在，不存在时才以“key”作为下标带入表达式中，同时出发错误事件，产生一条Notice级错误。因此，在绝大多数可以使用单引号的场合，禁止使用双引号。依据上述分析，可以或必须使用单引号的情况包括但不限于下述：字符串为固定值，不包含“\t”等特殊转义字符；数组的固定下标，例如$array[‘key’]；表达式中不需要带入变量，例如$string=‘test’;，而非$string=“test$var”；例外的，在正则表达式(用于preg_系列函数和ereg系列函数)中，Discuz!全部使用双引号，这是为了人工分析和编写的方便，并保持正则表达式的统一，减少不必要的分析混淆。数据库SQL语句中，所有数据必须加单引号，无论数值还是字串，以避免可能的注入漏洞和SQL错误。正确的写法为：6UPDATEcdb_membersSETadminid=’1’WHEREusername=’$admin’ANDadminid=’2’;所有数据在插入数据库之前，均需要进行addslashes()处理，以免特殊字符未经转义在插入数据库的时候出现错误。Discuz!中所有通过GET,POST,FILE,取得的变量默认情况下已经使用了addslashes()进行了转义，不必重复进行。如果数据处理必要(例如用于直接显示)，可以使用stripslashes()恢复，但数据在插入数据库之前必须再次进行转义。缓存文件中，一般对缓存数据的值采用addcslashes($string,'\'\\')进行转义。Discuz!语言问题在功能设计阶段，当需要使用中文或者给出用户中文提示的时候可以直接在程序中插入简体中文文字，待程序整理和测试阶段由专人进行语言分离工作；功能说明性语言、短语一般不使用“。”或者其他标点符号作为结束，文字中的标点符号，应使用全角。但注意：由于中英文模板与语言包问题，功能说明性的语言中，冒号使用半角”:”，而不使用全角；提示信息(用showmessage()和cpmsg()显示的)和使用技巧(如后台管理界面中的tips)等大篇幅文字中，当中的标点符号应当遵循中文语法规则，以使用全角中文标点为主，结尾应当加入全角句号。尽管程序语言包是在最后整理阶段才进行提取，但程序中直接写出的中文内容，也应充分保证书面语的特征：语言通顺、简洁、得体、无歧义。应彻底杜绝认为直接写提示语言是临时性操作的想法，反复推敲，并总结之前提示语言的特征规范，加以应用。良好的语言文字表达能力，是每个优秀程序员必须具备的基本素质之一。命名原则命名是程序规划的核心。古人相信只要知道一个人真正的名字就会获得凌驾于那个人之上的不可思议的力量。只要你给事物想到正确的名字，就会给你以及后来的人带来比代码更强的力量。名字就是事物在它所处的生态环境中一个长久而深远的结果。总的来说，只有了解系统的程序员才能为系统取出最合适的名字。如果所有的命名都与其自然相适合，则关系清晰，含义可以推导得出，一般人的推想也能在意料之中。就一般约定而言，类、函数和变量的名字应该总是能够描述让代码阅读者能够容易的知道这些代码的作用。形式越简单、越有规则，就越容易让人感知和理解。应该避免使用模棱两可，晦涩不7标准的命名。变量、对象、函数名变量、对象、函数名一律为小写格式，除非必要，单词之间一般不使用下划线“_”进行分割；以标准计算机英文为蓝本，杜绝一切拼音、或拼音英文混杂的命名方式；变量命名只能使用项目中有据可查的英文缩写方式，例如可以使用$data而不可使用$data1、$data2这样容易产生混淆的形式，应当使用$threaddata、$postdata这样一目了然容易理解的形式；可以合理的对过长的命名进行缩写，例如$bio($biography)，$tpp($threadsPerPage)，前提是英文中有这样既有的缩写形式，或字母符合英文缩写规范；必须清楚所使用英文单词的词性，在权限相关的范围内，大多使用$allow***或$is***的形式，前者后面接动词，后者后面接形容词。常量常量应该总是全部使用大写字母命名，少数特别必要的情况下，可使用划线来分隔单词；PHP的内建值TRUE、FALSE和NULL必须全部采用大写字母书写。变量的初始化与逻辑检查任何变量在进行累加、直接显示或存储前必需进行初使化,例如：$number=0;//数值型初始化$string=‘’;//字符串初始化$array=array();//数组初始化判断一个无法确定（不知道是否已被赋值）的变量时，可用empty()或isset()，而不要直接使用if($switch)的形式，除非你确切的知道此变量一定已经被初始化并赋值。empty()和isset