Typecho PHP 編碼規範

Typecho PHP 編碼規範

如果您已經決定向Typecho貢獻代碼，請詳細閱讀以下規範，並嚴格遵守。這樣在保證您代碼可讀性的同時還可以大大減少我們的工作量。

約定

文件編碼

請調整您的編輯器文件編碼爲UTF-8，並關閉UTF-8 BOM的功能。請不要使用windows自帶的記事本編輯項目文件。

縮進

詳細的代碼縮進會在後面提到，這裏需要注意的是，Typecho項目中的代碼縮進使用的是4個空格(space)，而不是製表符(tab)，請務必調整。

UNIX編碼規範

如果你正在編寫一個php文件，那麼根據UNIX的C語言編碼規範，必須留出最後一個空行。比如

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

而且，如果此文件爲純php文件(沒有嵌套HTML)，請不要用?>符號結尾，保持最後一行留空即可。

UNIX風格換行

我們在這裏使用UNIX風格的換行符，即只有換行(LF或”\n”)沒有回車(CR或”\r”)，請在你的編輯器內調整

命名

文件命名

Typecho的文件命名採用了與Zend Framework一致的命名方法，這也是大多數第三方擴展包所使用的命名方案。這種命名方法的準則是，class名稱與文件名關聯。關聯的方法是以包所在的目錄爲根目錄，到類所在的文件，將目錄分隔符改爲下劃線即爲此類的名稱。比如我們的包名稱爲Typecho，我們的類文件所在路徑爲Typecho/Db/Adapter.php，那麼這個類的名稱就是Typecho_Db_Adapter。

類命名

使用駱駝加下劃線法則，首字母大寫。

class Typecho_Db
{

函數(方法,接口)命名

使用駱駝法則，首字母小寫。

public function fetchRows(Typecho_Db_Query $query, array $filter = NULL)

變量命名

使用駱駝法則，首字母小寫。

protected $callbackFunctions;

如爲私有變量，請在變量名前方加上下劃線。

private $_adapter;

常量命名

所有字母大寫，前後加上雙下劃線，單詞之間用下劃線分割，如果是Typecho的內部常量，則需要加上TYPECHO前綴。

define('__TYPECHO_DB_ADAPTER__', 'Mysql');

註釋

註釋是開源項目的重點，請務必重視。

頭部註釋

頭部註釋主要用來闡述此文件的版權，協議，作者，版本。對於Typecho核心開發組，請按照下列形式書寫(你可以把它設置爲代碼模板)。

<?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$
 */

其中author爲作者的名稱，請自己命名。version定義爲$Id$是爲了匹配svn的關鍵字，設置此文件的svn:keywords屬性爲id，每次提交以後,$Id$就會被替換爲具體的版本信息，比如:$Id: Db.php 14 2008-02-23 13:07:16Z magike.net $。

引用文件和定義常量註釋

文件的引用和常量的定義一般都放置在文件的開頭部分。對於單行註釋，請參考c99標準。

/** 定義數據庫適配器 **/
define('__TYPECHO_DB_ADAPTER__', 'Mysql');
 
/** 數據庫異常 **/
require_once 'Db/Exception.php';

多行註釋，使用如下形式

/**
 * 定義數據庫查詢讀寫狀態
 * true表示讀狀態
 * false表示寫狀態
 *
 */
define('__TYPECHO_DB_READ__', true);
define('__TYPECHO_DB_WRITE__', false);

類(接口)註釋

一個類(接口)在聲明的時候必須聲明其作用，如果是類庫文件，則必須聲明其包所屬。此註釋參考phpdoc規範。

/**
 * 包含獲取數據支持方法的類
 * 必須定義__TYPECHO_DB_HOST__, __TYPECHO_DB_PORT__, __TYPECHO_DB_NAME__,
 * __TYPECHO_DB_USER__, __TYPECHO_DB_PASS__, __TYPECHO_DB_CHAR__
 *
 * @package Db
 */
class Typecho_Db
{

函數(方法,接口)註釋

函數(方法,接口)的聲明註釋參考phpdoc規範。注意，如果是無返回函數，必須指明@return void，請儘量在函數參數表中使用已知類型。如果函數中拋出異常則必須指明@throws <異常類型>。

/**
 * 一次取出所有行
 * 
 * @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__)
{

程序行間註釋

行間註釋採用雙斜線註釋法

//實例化適配器對象
$this->_adapter = new $adapter();

大括號放置

大括號換行規則與linux內核書寫規則一致。

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 {
        }

逗號放置

函數中用逗號來分隔參數，所有的參數與前面的逗號之間要空格(第一個參數除外)。

public function connect($host, $port, $db, $user, $password, $charset = NULL)

空格使用

除了參數之間要使用空格外，所有操作符之間都要使用空格，包括字符連接符(.)。

$host . ':' . $port

代碼佈局

類佈局

類的內部方法排序爲

__construct
private
protected
public
__destruct

屬性的排序爲

private
protected
public

空行使用

使用空行可以分割代碼的不同區塊，做建議，具體請各位自己把握。請不要使用每行一個空行編碼風格。