Typecho
PHP 编码规范
如果您已经决定向 Typecho (
网学)贡献代码,请详细阅读以下规范,并严格遵 守。这样在保证您代码可读性的同时还可以大大减少我们的
工作量。
约定
文件编码 请调整您的编辑器文件编码为*UTF-8*,并关闭 UTF-8 BOM*的功能。 关闭 的功能。 的功能 自带的记事本编辑项目文件。 请不要使用 windows 自带的记事本编辑项目文件。 缩进 详细的代码缩进会在后面提到,这里需要注意的是,Typecho 项目中的 代码缩进使用的是 4 个空格 个空格(space),而不是制表符(tab),请务必调整。 UNIX 编码规范 如果你正在编写一个 php 文件, 那么根据 UNIX 的 C 语言编码规范, 必 须留出最后一个空行。比如
而且,如果此文件为纯 php 文件(没有嵌套
HTML),请不要用?>符号结 尾,保持最后一行留空即可。
命名
文件命名 文件名与类名保持一致,区分大小写。在某些情况下文件名可以去掉类 名的前缀或后缀,比如所有的库类命名都要求加上 Typecho 的前缀,那 么这个类的文件则去掉前缀,详见这里 TypechoLibraryFileNaming。 类命名 使用骆驼法则,首字母大写。
class TypechoDb {
函数(方法 接口)命名 函数 方法,接口 命名 方法 接口 使用骆驼法则,首字母小写。
public function fetchRows(TypechoDbQuery $query, array $filter = NULL)
变量命名 使用骆驼法则,首字母小写。
protected $callbackFunctions;
如为私有变量,请在变量名前方加上下划线。
private $_adapter;
常量命名
所有字母大写,前后加上双下划线,单词之间用下划线分割,如果是 Typecho 的内部常量,则需要加上 TYPECHO 前缀。
define('__TYPECHO_DB_ADAPTER__', 'Mysql');
注释
注释是开源项目的重点,请务必重视。 头部注释 头部注释主要用来阐述此文件的
版权, 协议, 作者, 版本。 对于 Typecho 核心开发组,请按照下列形式书写(你可以把它设置为代码模板)。
其中 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__', 'My
sql'); /** 数据库异常 **/ require_once 'Db/DbException.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 TypechoDb {
函数(方法 接口)注释 函数 方法,接口 注释 方法 接口
函数(方法,接口)的声明注释参考 phpdoc 规范。注意,如果是无返回函 数,必须指明@return void,请尽量在函数参数表中使用已知类型。如 果函数中抛出异常则必须指明@throws <异常类型>。
/** * 一次取出所有行 * * @param TypechoDbQuery $query
查询对象 * @param array $filter 行过滤器函数,将查询的每一行作为第一个参数传 入指定的过滤器中 * @return array */ public function fetchRows(TypechoDbQuery $query, array $filter