您在这里: Typecho文档站点 » Typecho PHP 编码规范

差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

— phpcoding [2013/10/21 06:55] (当前版本)
行 1: 行 1:
 +====== 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>​
 +
 +==== 空行使用 ====
 +
 +使用空行可以分割代码的不同区块，做建议，具体请各位自己把握。请不要使用每行一个空行编码风格。
打印/导出