💎一站式轻松地调用各大LLM模型接口,支持GPT4、智谱、星火、月之暗面及文生图 广告
**每个程序均必须提供必要的注释,书写注释要求规范,参照PEAR提供的注释要求,为今后利用`phpdoc`生成 PHP 文档做准备。** ## 1、程序头注释块 每个程序头部必须有统一的注释块,规则如下:     a.必须包含本程序的描述;     b.必须包含作者;     c.必须包含书写日期;     d.必须包含版本信息;     e.必须包含项目名称;     f.必须包含文件的名称;     g.重要的使用说明,如类的调用方法、注意事项等; 参考例子如下: ~~~`` // // +---------------------------------------------------------+ // | PHP version 4.0 // +---------------------------------------------------------+ // | Copyright (c) 1997-2001 The PHP Group // +---------------------------------------------------------+ // | This source file is subject to of the PHP license, // | that is bundled with this packafile LICENSE, and is // | available at through the world-web at // | http://www.php.net/license/2_02.txt. // | If you did not receive a copy of the and are unable to // | obtain it through the world-wide-web,end a note to // | license@php.net so we can mail you a immediately. // +---------------------------------------------------------+ // | Authors: Stig Bakken // | Tomas V.V.Cox // // +———————————————————+ // // $Id: Common.php,v 1.8.2.3 2001/11/13 01:26:48 ssb Exp $ ~~~ ##2、类的注释 类的注释采用里面的参考例子方式: ~~~ /** * @ Purpose: * 访问数据库的类,以ODBC作为通用访问接口 * @Package Name: Database * @Author: Forrest Gump gump@crtvu.edu.cn * @Modifications: * No20020523-100: * odbc_fetch_into()参数位置第二和第三个位置调换 * John Johnson John@crtvu.edu.cn * @See: (参照) */ class Database { ... } ~~~ ##3、函数和方法的注释 函数和方法的注释写在函数和方法的前面,采用类似下面例子的规则: ~~~ /** * @Purpose: * 执行一次查询 * @Method Name: query() * @Param: string $queryStr SQL查询字符串 * @Param: string $username 用户名 * @Access: public * @Return: mixed 查询返回值(结果集对象) */ public function query ( $queryStr, $username ) { ... } ~~~ ##4、变量或者语句注释 程序中变量或者语句的注释遵循以下原则:     a.写在变量或者语句的前面一行,而不写在同行或者后面;     b.注释采用``/* */``的方式;     c.每个函数前面要包含一个注释块。内容包括函数功能简述,输入/输出参数,预期的返回值,出错代码定义;     d.注释完整规范;     e.把已经注释掉的代码删除,或者注明这些已经注释掉的代码仍然保留在源码中的特殊原因。 例子: ~~~ /** * @Purpose: * 数据库连接用户名 * @Attribute/Variable Name: db_user_name * @Type: string */ var db_user_name; ~~~ ##5、标注使用     IDE支持一些特殊注释,可以列出整个项目的特殊注释,方便后期的维护和代码检查,例如: ~~~ //@fixMe 表示需要修复项。如:修复了IP获取的一个安全漏洞 //@todo 表示需要完善的地方。如:这个函数的效率太低,需要改进。 ~~~     上述注释和java中的标注及注解比较相像。可以查看NetBeans中标注的效果。     不同的IDE对这类特殊注释的支持程度不一。为了编码效率和团队协作,建议在项目开发时使用IDE进行项目管理。     对于代码不推荐使用的函数或方法,使用@Deprecated注释;对于重载方法,使用@over load注释。