MooPHP PHP 编码规范

当一个软件项目尝试着遵守公共一致的标准时，可以使参与项目的开发人员更容易了解项目中的代码、弄清程序的状况。使新的参与者可以很快的适应环境，防止部分参与者出于节省时间的需要，自创一套风格并养成终生的习惯，导致其它人在阅读时浪费过多的时间和精力。而且在一致的环境下，也可以减少编码出错的机会。缺陷是由于每个人的标准不同，所以需要一段时间来适应和改变自己的编码风格，暂时性的降底了工作效率。从使项目长远健康的发展以及后期更高的团队工作效率来考虑暂时的工作效率降低是值得的，也是必须要经过的一个过程。标准不是项目成功的关键，但可以帮助我们在团队协作中有更高的效率并且更加顺利的完成既定的任务。

1. 程序员可以了解任何代码，弄清程序的状况
2. 新人可以很快的适应环境
3. 防止新接触PHP的人出于节省时间的需要，自创一套风格并养成终生的习惯
4. 防止新接触PHP的人一次次的犯同样的错误
5. 在一致的环境下，人们可以减少犯错的机会
6. 程序员们有了一致的敌人

如果您已经决定向MooPHP贡献代码，请详细阅读以下规范，并严格遵守。这样在保证您代码可读性的同时还可以大大减少我们的工作量。

对于在MooPHP文件夹下面的MooPHP核心文件，是默认的ANSI编码，注释为中文。

其他涉及具体程序的代码，请调整您的编辑器文件编码为UTF-8，并关闭UTF-8 BOM的功能。请不要使用windows自带的记事本编辑项目文件。

文件名与类名保持一致，区分大小写。在某些情况下文件名可以去掉类名的前缀或后缀，比如所有的库类命名都要求加上Moo的前缀，那么这个类的文件则去掉前缀，详见这里[MooPHPLibraryFileNaming]。

使用骆驼法则，首字母大写，专有名词保持其默认大小写规范。

class MooMySQL{

使用Moo前缀 + 骆驼法则的形式实现，首字母小写。

function MooAddslashes($value, $force = 0) {
	return $value = is_array($value) ? array_map('MooAddslashes', $value) : addslashes($value);
}

使用骆驼法则，首字母小写。为了兼容PHP4的服务器环境，更详细的类定义与方法、接口命名请参考[MooPHPLibraryClassNaming]

function stripvTag($s) {
	return preg_replace("/$this->vtag_regexp/is", "\\1", str_replace("\\\"", '"', $s));
}

使用骆驼法则，首字母小写。

$callbackFunctions;

所有字母大写，单词之间用下划线分割，如果是MooPHP的内部常量，则需要加上MooPHP前缀。

define('MAGIC_QUOTES_GPC', get_magic_quotes_gpc());

注释是开源项目的重点，请务必重视。

头部注释主要用来阐述此文件的版权，协议，作者，版本。对于MooPHP核心开发组，请按照下列形式书写(你可以把它设置为代码模板)。

<?php
/*
	More & Original PHP Framwork
	Copyright (c) 2007 - 2008 IsMole Inc.
 
	$Id$
*/

其中author为作者的名称，请自己命名。version定义为$Id$是为了匹配svn的关键字，设置此文件的svn:keywords属性为id，每次提交以后,$Id$就会被替换为具体的版本信息，比如:$Id: MooPHP.php 52 2008-03-31 08:24:35Z kimi $。

文件的引用和常量的定义一般都放置在文件的开头部分。对于单行注释，请参考c99标准。

/** 定义GPC变量 **/
define('MAGIC_QUOTES_GPC', get_magic_quotes_gpc());

多行注释，使用如下形式

/**
 * 定义数据库缓存存储方式
 * true表示...
 * false表示...
 *
 */
define('MooPHP_DB_FILECACHE', true);
define('MooPHP_DB_DBCACHE', false);

一个类(接口)在声明的时候必须声明其作用，如果是类库文件，则必须声明其包所属。此注释参考phpdoc规范。

/**
 * 包含获取数据支持方法的类
 */
class MooPHPDb{

函数(方法,接口)的声明注释参考phpdoc规范。注意，如果是无返回函数，必须指明@return void，请尽量在函数参数表中使用已知类型。如果函数中抛出异常则必须指明@throws <异常类型>。

/**
* 获取GPC变量。对于type为integer的变量强制转化为数字型
* @param string $key - 权限表达式
* @param string $type - integer 数字类型；string 字符串类型；array 数组类型
* @param string $var - R $REQUEST变量；G $GET变量；P $POST变量；C $COOKIE变量
* @return string
*/
function MooGetGPC($key, $type = 'integer', $var = 'R') {

行间注释采用双斜线注释法

//note 禁止对全局变量注入
if (isset($_REQUEST['GLOBALS']) OR isset($_FILES['GLOBALS'])) {
	exit('Request tainting attempted.');
}

详细的代码缩进会在后面提到，这里需要注意的是，MooPHP项目中的代码缩进使用每个缩进的单位约定是一个TAB(8个空白字符宽度)，需每个参与项目的开发人员在编辑器(UltraEdit、EditPlus、Zend Studio等)中进行强制设定，以防在编写代码时遗忘而造成格式上的不规范。

本缩进规范适用于PHP、Javascript中的函数、类、逻辑结构、循环等。

如果你正在编写一个php文件，那么根据UNIX的C语言编码规范，必须留出最后一个空行。比如

<?php
//this is a test file
echo 'hello';
<---这行留空

而且，如果此文件为纯php文件(没有嵌套HTML)，请不要用?>符号结尾，保持最后一行留空即可。

• 首括号与关键词同行，尾括号与关键字同列；
• if结构中，else和elseif与前后两个大括号同行，左右各一个空格。另外，即便if后只有一行语句，仍然需要加入大括号，以保证结构清晰；
• switch结构中，通常当一个case块处理后，将跳过之后的case块处理，因此大多数情况下需要添加break。break的位置视程序逻辑，与case同在一行，或新起一行均可，但同一switch体中，break的位置格式应当保持一致。

以下是符合上述规范的例子：

if($condition) {
	switch($var) {
		case 1: 	echo ‘var is 1’; break;
		case 2: 	echo ‘var is 2’; break;
		default: 	echo ‘var is neither 1 or 2’; break;
	}
} else {
	Switch($str) {
		case ‘abc’:
			$result = ‘abc’;
			break;
		default:
			$result = ‘unknown’;
			break;
	}
}

• 每个运算符与两边参与运算的值或表达式中间要有一个空格，唯一的特例是字符连接运算符号两边不加空格；
• 左括号“(” 应和函数关键词紧贴在一起，除此以外应当使用空格将“(”同前面内容分开；
• 右括号“)”除后面是“)”或者“.”以外，其他一律用空格隔开它们；
• 除字符串中特意需要，一般情况下，在程序以及HTML中不出现两个连续的空格；
• 任何情况下，PHP程序中不能出现空白的带有TAB或空格的行，即：这类空白行应当不包含任何TAB或空格。同时，任何程序行尾也不能出现多余的TAB或空格。多数编辑器具有自动去除行尾空格的功能，如果习惯养成不好，可临时使用它，避免多余空格产生；
• 每段较大的程序体，上、下应当加入空白行，两个程序块之间只使用1个空行，禁止使用多行；
• 程序块划分尽量合理，过大或者过小的分割都会影响他人对代码的阅读和理解。一般可以以较大函数定义、逻辑结构、功能结构来进行划分。少于15行的程序块，可不加上下空白行；
• 说明或显示部分中，内容如含有中文、数字、英文单词混杂，应当在数字或者英文单词的前后加入空格。

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

$result = (($a + 1) * 3 / 2 + $num)).’Test’;
$condition ? func1($var) : $func2($var); 
$condition ? $long_statement
	: $another_long_statement;
if($flag) {
 
	//Statements(more than 15 lines)
 
}

• 参数的名字和变量的命名规范一致；
• 函数定义中的左小括号，与函数名紧挨，中间无需空格；
• 开始的左大括号与函数定义为同一行，中间加一个空格，不要另起一行；
• 具有默认值的参数应该位于参数列表的后面；
• 函数调用与定义的时候参数与参数之间加入一个空格；
• 必须仔细检查并切实杜绝函数起始缩进位置与结束缩进位置不同的现象。

function MooGetGPC($k, $type = 'ini', $var = 'R') {
	if($flag) {
		//Statement
	}
}