====== Typecho PHP 编码规范 ======

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

===== 约定 =====

==== 文件编码 ====

请调整您的编辑器文件编码为**UTF-8**，并**关闭UTF-8 BOM**的功能。请不要使用windows自带的记事本编辑项目文件。

==== 缩进 ====

详细的代码缩进会在后面提到，这里需要注意的是，Typecho项目中的代码缩进使用的是**4个空格(space)**，而不是制表符(tab)，请务必调整。

==== UNIX编码规范 ====

如果你正在编写一个php文件，那么根据UNIX的C语言编码规范，必须留出最后一个空行。比如
<code php>
<?php
//this is a test file
echo 'hello';
<---这行留空
</code>
而且，如果此文件为纯php文件(没有嵌套HTML)，请不要用**?>**符号结尾，保持最后一行留空即可。

==== UNIX风格换行 ====

我们在这里使用UNIX风格的换行符，即只有换行(LF或"\n")没有回车(CR或"\r")，请在你的编辑器内调整

===== 命名 =====
==== 文件命名 ====

Typecho的文件命名采用了与Zend Framework一致的命名方法，这也是大多数第三方扩展包所使用的命名方案。这种命名方法的准则是，class名称与文件名关联。关联的方法是以包所在的目录为根目录，到类所在的文件，将目录分隔符改为下划线即为此类的名称。比如我们的包名称为Typecho，我们的类文件所在路径为Typecho/Db/Adapter.php，那么这个类的名称就是Typecho_Db_Adapter。

==== 类命名 ====

使用骆驼加下划线法则，首字母大写。
<code php>
class Typecho_Db
{
</code>

==== 函数(方法,接口)命名 ====

使用骆驼法则，首字母小写。
<code php>
public function fetchRows(Typecho_Db_Query $query, array $filter = NULL)
</code>

==== 变量命名 ====

使用骆驼法则，首字母小写。
<code php>
protected $callbackFunctions;
</code>

如为私有变量，请在变量名前方加上下划线。
<code php>
private $_adapter;
</code>

==== 常量命名 ====

所有字母大写，前后加上双下划线，单词之间用下划线分割，如果是Typecho的内部常量，则需要加上TYPECHO前缀。
<code php>
define('__TYPECHO_DB_ADAPTER__', 'Mysql');
</code>

===== 注释 =====

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

==== 头部注释 ====

头部注释主要用来阐述此文件的版权，协议，作者，版本。对于Typecho核心开发组，请按照下列形式书写(你可以把它设置为代码模板)。
<code php>
<?php
/**
 * Typecho Blog Platform
 *
 * @author     qining
 * @copyright  Copyright (c) 2008 Typecho team (http://www.typecho.org)
 * @license    GNU General Public License 2.0
 * @version    $Id$
 */
</code>
其中author为作者的名称，请自己命名。version定义为$Id$是为了匹配svn的关键字，设置此文件的svn:keywords属性为id，每次提交以后,$Id$就会被替换为具体的版本信息，比如:$Id: Db.php 14 2008-02-23 13:07:16Z magike.net $。
==== 引用文件和定义常量注释 ====

文件的引用和常量的定义一般都放置在文件的开头部分。对于单行注释，请参考c99标准。
<code php>
/** 定义数据库适配器 **/
define('__TYPECHO_DB_ADAPTER__', 'Mysql');

/** 数据库异常 **/
require_once 'Db/Exception.php';
</code>
多行注释，使用如下形式
<code php>
/**
 * 定义数据库查询读写状态
 * true表示读状态
 * false表示写状态
 *
 */
define('__TYPECHO_DB_READ__', true);
define('__TYPECHO_DB_WRITE__', false);
</code>
==== 类(接口)注释 ====

一个类(接口)在声明的时候必须声明其作用，如果是类库文件，则必须声明其包所属。此注释参考phpdoc规范。
<code php>
/**
 * 包含获取数据支持方法的类
 * 必须定义__TYPECHO_DB_HOST__, __TYPECHO_DB_PORT__, __TYPECHO_DB_NAME__,
 * __TYPECHO_DB_USER__, __TYPECHO_DB_PASS__, __TYPECHO_DB_CHAR__
 *
 * @package Db
 */
class Typecho_Db
{
</code>
==== 函数(方法,接口)注释 ====

函数(方法,接口)的声明注释参考phpdoc规范。注意，如果是无返回函数，必须指明@return void，请尽量在函数参数表中使用已知类型。如果函数中抛出异常则必须指明@throws <异常类型>。
<code php>
/**
 * 一次取出所有行
 * 
 * @param TypechoDbQuery $query 查询对象
 * @param array $filter 行过滤器函数,将查询的每一行作为第一个参数传入指定的过滤器中
 * @return array
 */
public function fetchRows(Typecho_Db_Query $query, array $filter = NULL)
{

/**
 * 数据库类构造函数
 * 
 * @param string $adapter 数据库适配器名称
 * @return void
 * @throws TypechoDbException
 */
public function __construct($adapter = __TYPECHO_DB_ADAPTER__)
{
</code>

==== 程序行间注释 ====

行间注释采用双斜线注释法
<code php>
//实例化适配器对象
$this->_adapter = new $adapter();
</code>

===== 大括号放置 =====

**大括号换行规则与linux内核书写规则一致**。
<code php>
class TypechoDb
{
    public function __construct($adapter = __TYPECHO_DB_ADAPTER__)
    {
        if (!defined($const = '__TYPECHO_DB_HOST__') || 
        !defined($const = '__TYPECHO_DB_PORT__') || 
        !defined($const = '__TYPECHO_DB_NAME__') || 
        !defined($const = '__TYPECHO_DB_USER__') || 
        !defined($const = '__TYPECHO_DB_PASS__') ||
        !defined($const = '__TYPECHO_DB_CHAR__')) {
        } else {
        }
</code>


===== 逗号放置 =====

函数中用逗号来分隔参数，所有的参数与前面的逗号之间要空格(第一个参数除外)。
<code php>
public function connect($host, $port, $db, $user, $password, $charset = NULL)
</code>

===== 空格使用 =====

除了参数之间要使用空格外，所有操作符之间都要使用空格，包括字符连接符(.)。
<code php>
$host . ':' . $port
</code>

===== 代码布局 =====


==== 类布局 ====

类的内部方法排序为
<code java>
__construct
private
protected
public
__destruct
</code>
属性的排序为
<code java>
private
protected
public
</code>

==== 空行使用 ====

使用空行可以分割代码的不同区块，做建议，具体请各位自己把握。请不要使用每行一个空行编码风格。