1. 程序注释
程序注释的原则如下:
写在被注释代码前面,而不是后面,但对于单行语句,按照习惯可以把注释放在语句的末尾。
对于大段注释,使用/**/格式,通常在文件和函数注释中使用,而代码内部统一使用//注释,因为其写起来简单。
注释不必太多,大家都看得懂的行不必注释。
2. 文件注释
文件注释通常放在整个PHP文件头部,其内容包括文件版权、作者、编写日期、版本号等重要信息。PHP中,可以参照phpdocument规范,便于利用程序自动生成文档。
文件注释需要包含以下规则:
1)必须包含本程序的概述
2)必须包含作者
3)必须包含项目名称
4)必须包含文件名称
5)可以包含书写日期
6)可以包含版本信息
7)可以包含重要使用说明。
3. 类/接口注释
类/接口的注释应该尽量简洁。按照一般的习惯,一个文件只包含一个类,在注释中通常不需要再加上作者和版本信息,加上可见性和简单的描述即可。如果文件注释已经足够详细。可以不用各类注释。如果同时存在接口和接口的实现类,只需要给接口中加注释。
4. 方法和函数注释
方法和函数注释写在前面,通常需要标明的信息主要是可见性、参数类型和返回值的类型。