编码规范（三）之注释规范

1.  程序注释

    程序注释的原则如下：

        写在被注释代码前面，而不是后面，但对于单行语句，按照习惯可以把注释放在语句的末尾。

        对于大段注释，使用/**/格式，通常在文件和函数注释中使用，而代码内部统一使用//注释，因为其写起来简单。

        注释不必太多，大家都看得懂的行不必注释。

2. 文件注释

    文件注释通常放在整个PHP文件头部，其内容包括文件版权、作者、编写日期、版本号等重要信息。PHP中，可以参照phpdocument规范，便于利用程序自动生成文档。

    文件注释需要包含以下规则：

    1）必须包含本程序的概述

    2）必须包含作者

    3）必须包含项目名称

    4）必须包含文件名称

    5）可以包含书写日期

    6）可以包含版本信息

    7）可以包含重要使用说明。

3. 类/接口注释

    类/接口的注释应该尽量简洁。按照一般的习惯，一个文件只包含一个类，在注释中通常不需要再加上作者和版本信息，加上可见性和简单的描述即可。如果文件注释已经足够详细。可以不用各类注释。如果同时存在接口和接口的实现类，只需要给接口中加注释。

4.  方法和函数注释

    方法和函数注释写在前面，通常需要标明的信息主要是可见性、参数类型和返回值的类型。