个人规范 · 测试文档

个人规范： ## **一、类命名** 驼峰命名：TestClass {} ### **1、成员属性命名**： 1、驼峰命名 2、公共成员属性：public $publicAttribute = ''; 3、可继承成员属性（单下划线）：protected $_protectedAttribute = ''; 4、私有成员属性（双下划线）：private $__privateAttribute = ''; 普通变量名命名： 1、驼峰命名，首字母小写：$varName = ''; ## **二、PHP文件约定** ### **1、文件编码** （1）、编辑器文件编码为UTF-8，并关闭UTF-8 BOM的功能（2）、不要使用windows自带的记事本编辑项目文件 ### **2、代码缩进问题** （1）使用4个空格，而不是制表符(tab) ### **3、UNIX编码规范** （1）、php文件必须留出最后一个空行（2）、如果此文件为纯php文件(没有嵌套HTML)，请不要用?>符号结尾，保持最后一行留空即可 ~~~ <?php //this is a test file echo 'hello'; //<---这行留空 ~~~ ### **4、UNIX风格换行** （1）使用UNIX风格的换行符，即只有换行(LF或"\\n")没有回车(CR或"\\r")，请在你的编辑器内调整 ### **5、php标签** （1）不使用php短标签，必须使用标准标签 ### **6、行的最大长度** （1）一行 80 字符以内是比较合适，应当努力在可能的情况下保持每行代码少于 80 个字符，在有些情况下，长点也可以, 但最多为 120 个字符 ### **7、行尾空格** （1）行尾已经去除空格 ### **8、大括号放置** （1）函数的起始大括号放在参数+空格后（2）结束大括号一般独自占据一行 ~~~ 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 { } } } ~~~ ### **9、空格使用** （1）除了参数之间要使用空格外，所有操作符之间都要使用空格，包括字符连接符(.) ~~~ $host . ':' . $port ~~~ （2）函数名和括参数的圆括号中间没有空格 ~~~ function save(&$sdf, $mustUpdate = null) { } //function和函数名之间只能有一个空格 ~~~ （3）使用 if 和 elseif 的控制语句在条件语句的圆括号前后都必须有一个空格~~~ ~~~ if ($a != 2) { $a = 2; } elseif ($a == 3) { $a = 4; } else{ $a = 7; } ~~~ ### **10、逗号放置** （1）函数中用逗号来分隔参数，所有的参数与前面的逗号之间要空格(第一个参数除外) ~~~ public function getList($cols='*', $filter=array(), $offset=0, $limit=-1, $orderby=null) ~~~ ### **11、字符串文字** （1）当字符串是文字(不包含变量)，应当用单引号（ apostrophe ）来括起来 ~~~ $a = 'Example String'; ~~~ ### **12、包含单引号（'）的字符串文字** （1）当文字字符串包含单引号（apostrophe ）就用双引号括起来，特别在 SQL 语句中有用 ~~~ $sql = "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'"; //Note:在转义单引号时，上述语法是首选的，因为很容易阅读。 ~~~ ### **13、变量替换** （1）变量替换有下面这些形式 ~~~ $greeting = "Hello $name, welcome back!"; $greeting = "Hello {$name}, welcome back!"; ~~~ 为保持一致，这个形式不允许 ~~~ $greeting = "Hello ${name}, welcome back!"; ~~~ ### **14、字符串连接** （1）字符串必需用 "." 操作符连接，在它的前后加上空格以提高可读性 ~~~ $company = 'EC' . ' ' . 'Store'; ~~~ ### **15、函数和方法的传址引用** （1）传址在调用时是严格禁止的。示例 ~~~ class Foo { public function bar(&$baz) { } } ~~~ 正确示范 ~~~ $this->bar($baz); ~~~ 错误示范 ~~~ $this->bar(&$baz); ~~~ ### **16、 if/else/elseif语句** （1）如果是单条if语句，后面大括号可省略 ~~~ //推荐示范 if ($a != 2) $a = 2; ~~~ （2）如果是有else则把大括号放下来 ~~~ if ($a != 2) { $a = 2; }else { $a = 1; } ~~~ ### **17、switch 语句** （1）在 "switch" 结构里的控制语句在条件语句的圆括号前后必须都有一个单个的空格（2）"switch" 里的代码必须有四个空格缩进，在"case"里的代码再缩进四个空格: ~~~ switch ($numPeople) { case 1: break; case 2: break; default: break; } ~~~ （3）switch 语句应当有 default ## **三、注释** ### **1、头部注释** （1）头部注释主要用来阐述此文件的版权，协议，作者，版本。对于ecos核心开发组，请按照下列形式书写(你可以把它设置为代码模板)。 ~~~ <?php /** * Ecos Platform * * @author 123 * @copyright Copyright (c) 2005-2014 * @license http://***.cn */ ~~~ (其中author为作者的名称，请自己命名) ### **2、引用文件和定义常量注释** （1）文件的引用和常量的定义一般都放置在文件的开头部分 ### **3、类(接口)注释** （1）一个类(接口)在声明的时候必须声明其作用，如果是类库文件，则必须声明其包所属。此注释参考phpdoc规范。 ~~~ /** * setting-系统配置类 * * @copyright Copyright (c) 2005-2014 * @license http://***.cn * @package base * @author 123 * @license */ class BaseSetting { } ~~~ ### **4、函数(方法,接口)注释** （1）、函数(方法,接口)的声明注释参考phpdoc规范（2）Note:如果是无返回函数，必须指明@return void，请尽量在函数参数表中使用已知类型。如果函数中抛出异常则必须指明@throws 。次数使用sublime插件 ``` /** * [increment description] * @param [type] $key [description] * @param integer $offset [description] * @return [type] [description] */ public function increment($key, $offset=1) { /** * [apply description] * @param [array] &$object [引用的一个商品信息] * @param [array] $aConfig [优惠的设置] * @param [array] &$cart_object [购物车信息(预过滤的时候这个为null)] * @return [void] [引用处理了,没有返回值] */ public function apply(&$object,$aConfig,&$cart_object = null) { } } ``` ### **5、程序行间注释** （1）行间注释采用双斜线注释法 ~~~ //实例化适配器对象 $this->_adapter = new $adapter(); ~~~ ## **四、代码布局** ### **1、类布局** （1）类的内部方法排序为: * \_construct * private * protected * public * \_\_destruct （2）属性的排序为: * const * private * protected * public ### **2、空行使用** （1）使用空行可以分割代码的不同区块，做建议，具体请各位自己把握。（2）请不要使用每行一个空行编码风格 ## **五、备注：phpdoc的一些常用属性** ~~~ /** * @name 名字 * @abstract 申明变量/类/方法 * @access 指明这个变量、类、函数/方法的存取权限 * @author 函数作者的名字和邮箱地址 * @category 组织packages * @copyright 指明版权信息 * @const 指明常量 * @deprecate 指明不推荐或者是废弃的信息 * @example 示例 * @exclude 指明当前的注释将不进行分析，不出现在文挡中 * @final 指明这是一个最终的类、方法、属性，禁止派生、修改。 * @global 指明在此函数中引用的全局变量 * @include 指明包含的文件的信息 * @link 定义在线连接 * @module 定义归属的模块信息 * @modulegroup 定义归属的模块组 * @package 定义归属的包的信息 * @param 定义函数或者方法的参数信息 * @return 定义函数或者方法的返回信息 * @see 定义需要参考的函数、变量，并加入相应的超级连接。 * @since 指明该api函数或者方法是从哪个版本开始引入的 * @static 指明变量、类、函数是静态的。 * @throws 指明此函数可能抛出的错误异常,极其发生的情况 * @todo 指明应该改进或没有实现的地方 * @var 定义说明变量/属性。 * @version 定义版本信息 */ ~~~