注释规范非常影响自身和别人的编程体验,不管别人怎样吧,自己写的遵守以下规范:
1、文件注释
a.注释开始 /* 不可以 /**,结束 */ 不可以 **/。
b.第二行php版本信息,版本信息后一空行。
c.注解内容对齐,注解之间不可有空行。
d.星号和注释内容中间必须是一个空格。
e.保持注解顺序一致@copyright然后@link再@license。
<?php /* * PHP version 5.5 * * @copyright Copyright (c) 2005-2015 YANTENG Inc. (http://www.xxx.com) * @link http://www.xxx.com * @license xxx公司版权所有 */ namespace VendorgiPackage; class ClassName{ public function aVeryLongMethodName(ClassTypeHint $arg1,&$arg2,array $arg3 = []){ // method body } }
2、类注释
a.注释开始 /** 不可以 /*,结束 */ 不可以 **/。
b.第二行开始描述,描述后一空行。
c.注解内容对齐,注解之间不可有空行。
d.星号和注释内容中间必须是一个空格。
e.保持注解顺序一致@author然后@since再@version。
<?php namespace VendorgiPackage; /** * 我是类描述信息哦! * * @author Author * @since 2015年1月12日 * @version 1.0 */ class ClassName{ public function aVeryLongMethodName(ClassTypeHint $arg1,&$arg2,array $arg3 = []){ // method body } }
3、属性注释
a.注释开始 /** 不可以 /*,结束 */ 不可以 **/。
b.星号和注释内容中间必须是一个空格。
c.使用var注解并注明类型。
d.注解基本类型包括int、sting、array、boolea、具体类名称。
<?php class Cache{ /** * 缓存的键值 * @var string */ public static $cacheKey = ''; /** * 缓存的键值 * @var string */ public static $cacheTime = 60; /** * 缓存的对象 * @var CacheServer */ public static $cacheObj = null;
4、方法注释
a.注释开始 /** 不可以 /*,结束 */ 不可以 **/。
b.第二行开始方法描述,方法描述后一空行。
c.注解内容对齐,注解之间不可有空行。
d.星号和注释内容中间必须是一个空格。
e.注解顺序为@param,@return,@author和@since,参数的顺序必须与方法参数顺序一致。
f.参数和返回值注解包括基本类型(int sting array boolean和unknown)和对象,如果多个可能类型使用|分割。
g.如果参数类型为对像必须指定参数类型为具体的类名,如下的$arg1参数。
h.如果参数类型为array必须指定参数类型为array。如下$arg2。
i.需要作者和日期注解,日期为最后修改日期。
<?php /** * 我是方法描述信息 * * @param ClassName $arg1 参数1描述 我是具体的对象类型哦 * @param array $arg2 参数2描述 我是数据类型哦 * @param int $arg3 参数3描述 我是基本数据类型哦 * @return boolean * @author Author * @since 2015年1月12日 */ public function methodName(ClassName $arg1,array $arg2,$arg3) { // method body return true; }
5、其他注释:
a.代码注释尽量使用 //
b.注释内容开始前必须一个空格
c.代码行尾注释//前面必须一个空格
d.代码注释与下面的代码对齐
<?php public function methodName(ClassName $arg1, array $arg2, $arg3) { // 这里是注释哦 注释内容前是有一个空格的哦 for ($i = 0; $i < 10; $i++) { //for body注释和下面的代码是对齐的哦 $a++; // 代码行尾注释‘//’前面必须一个空格 } return true; }
//多行注释时使用 /* * ......*/ public function methodName(ClassName $arg1, array $arg2, $arg3) { /** * 这是多行注释哦 * 这是多行注释哦 */ for ($i = 0; $i < 10; $i++) { // for body } }