PHP学习记录【php注释】

• 注释可以理解为对代码的解释和说明，是程序中不可缺少的重要元素。使用注释不仅能够提高程序的可读性，而且还有利于程序的后期维护工作。
• 注释不会影响程序的执行，因为在程序执行时，注释部分的内容不会被解释器执行。
• 注释通常在 PHP 代码块中编写的，它是一个不可执行的部分，不会显示在输出结果中，在程序运行过程中会被解释器直接忽略。

1.单行注释

示例代码如下：

<?php
#这是第一行注释
echo "老男孩教育<br>";
//这是第二行注释
echo "单行注释";
// echo "PHP 注释";
?>

上面的代码中示例中，第二行使用“#”定义了一条注释，并分别在第四行和第六行使用“//”定义了一条注释。在一行中所有 “//” 符号右面的文本都被视为注释， 因为 PHP 解析器忽略该行 “//” 右面的所有内容。也可以一行只写注释，不写代码。提示：单行注释中使用最广泛是使用双斜杠“//”来定义注释。

运行结果如下：

老男孩教育
单行注释

C++风格的单行注释（//）

<?php
    echo '使用C++风格';  //这就是C++风格
?>

注意：在单行注释中的内容不要出现“?>”标志，因为解释器会认为PHP脚本结束，而去执行“?>”后面的代码

错误演示：

<?php
    echo ‘这样会出错的！！！！！’  //不会看到?>会看到
?> 

2. 多行注释

多行注释用于注释多行内容，经常用于多行文本的注释。注释的内容需要包含在（/* 和 /）中，以“/”开头，以“*/”结尾。

示例代码如下：

<?php
    /*
        这是一个多行注释
        输出网站名称及链接地址
    */
    echo "老男孩教育<br>";
    echo "网络安全";
    /* echo "PHP 注释"; */
?>

运行结果如下：

老男孩教育
网络安全

提示：多行注释不能相互嵌套使用。C 风格的多行注释在碰到第一个 / 时结束。要确保不要嵌套 C 风格的多行注释注释。试图注释掉一大块代码时很容易出现该错误。多行注释经常被开发人员用来介绍某个函数或方法的功能以及参数。另外需要注意的是，多行注释是由“/”和“*/”两个标记构成的，忽略任何一个都不行。

3.类的注释，类名及介绍

/** 
* 类的介绍 
* 
* 类的详细介绍（可选。）。 
* @author      alvin 作者 
* @version     1.0 版本号
*/

4.函数的注释，函数作用，参数介绍及返回类型

/**  
* 函数的含义说明 
* 
* @access public 
* @param mixed $arg1 参数一的说明 
* @param mixed $arg2 参数二的说明 
* @param mixed $mixed 这是一个混合类型 
* @return array 返回类型
*/  

5.文件头的注释，介绍文件名，功能以及作者版本号等信息

/** 
*文件名简单介绍
* 
*文件功能。 
* @author      alvin 作者
* @version     1.0 版本号
*/ 

我们在平常写代码或看别人写的代码时, 在方法的说明注释中经常会有这样的注释:

/**
 * @param $num
 * @return array
 */

上面的@param @return 就是注释标记

注释标记用于生成文档, param指明需要接收的参数, return指明返回值

在使用 phpDocumentor 等工具生成文档时, 会识别相关注释, 而且IDE也会识别, 在编码的过程中会给出提示.

PHP注释标记总结
@api: 提供给第三方使用的接口
@author: 标明作者
@param: 参数
@return: 返回值
@todo: 待办
@version: 版本号
@inheritdoc: 文档继承
@property: 类属性
@property-read: 只读属性
@property-write: 只写属性
@const: 常量
@deprecated: 过期方法
@example: 示例
@final: 标识类是终态, 禁止派生
@global: 指明引用的全局变量
@static: 标识类、方法、属性是静态的
@ignore: 忽略
@internal: 限内部使用
@license: 协议
@link: 链接,引用文档等
@see: 与 link 类似, 可以访问内部方法或类
@method: 方法
@package: 命名空间
@since: 从指定版本开始的变动
@throws: 抛出异常
@uses: 使用
@var: 变量
@copyright: 版权声明

所谓注释，汉语解释可以为：注解。更为准确一些。因为代码是英文的、并且代码很长，时间长了人会忘。所以我们会加上注释。

注释的功能有很多：
1.对重点进行标注
2.时间长了容易忘快速回忆，方便查找
3.让其他人看的时候快速看懂
4.还可以生成文档，代码写完相关的文档就写完了，提高工作效率
5.注释、空行、回车之后的代码看起来更优美
6.注释可用来排错。不确定代码中哪一块写错了，可以将一大段注释，确定错误区间
7.注释中间的部份的内容，电脑不会执行它