PHP编码的注释规范 - 自用笔记

注释规范非常影响自身和别人的编程体验，不管别人怎样吧，自己写的遵守以下规范：

 

 

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