【PHP】如何优雅地在PHP里写注释 | PHP的注释、PHPDoc

一、没有注释的代码就像是吃饭不给筷子

你好，我是小雨青年，一名知道如何写注释的程序员。

注释，字面上的意思，就是解释性质的文字，而代码上的注释，说是一种艺术也不为过。

本篇内容你将会学到：

• PHP的注释格式以及应用范围
• 如何规范注释

二、PHP的注释方式

1. 行内注释

行内注释的作用是对单行代码进行注释，说明单行代码的作用。

$name = '小雨青年'; //给name赋值小雨青年
1

上面仅作为注释的演示，实际项目中这样注释是无效并且拖沓的，不建议哦。

2. 多行注释

多行注释一般用在需要写入大量换行文字上，比如复杂的业务说明和复杂的内部实现。

    /*
      多行注释的中间行不用带星号。
                  by 小雨青年
     */
1
2
3
4

目前这样的方式不常见了，IDE内的注释方式是每行带着星号的。

和下面的注释区分的是，多行注释的第一行带1个星号。

多行注释的内容和上下文不是强制关联，使用起来和单行注释一样随意。

三、PHPDoc的注释

1. PHPDoc是什么

phpDocumentor 是 PHP 项目事实上的文档应用程序。 您的项目也可以从 20 多年的经验中受益，并为 PHP 应用程序文档设定标准。

简单来说，它是一个文档规范，目前的ide也是默认使用的。

下图是我从PHPStom的配置找到的相关配置，你可以根据自己的习惯或者团队的要求合理配置。

2. 注释的基本格式

这是laravel内的log注释。

    /**
     * Create a new event instance.
     *
     * @param  string  $level
     * @param  string  $message
     * @param  array  $context
     * @return void
     */
    public function __construct($level, $message, array $context = [])
    {
        $this->level = $level;
        $this->message = $message;
        $this->context = $context;
    }
1
2
3
4
5
6
7
8
9
10
11
12
13
14

我们可以看到如下特点

• 写在方法上面没有换行
• 以/**作为开始
• 第一行为对方法的说明
• @param为对应参数的说明，对应数据类型、参数名，后面还可以跟文字说明
• @return为返回值

上面提到的，IDE对于PHPdoc格式的完全兼容，我们可以很方便看到注释，比如你在鼠标悬停的时候，就可以看到。

3. 完整的注释标签

下面是所有的标签，点击可以查看官网的相关说明。

• @api
• @author
• @category
• @copyright
• @deprecated
• @example
• @filesource
• @global
• @ignore
• Tag reference
• @internal
• @license
• @link
• @method
• @package
• @param
• @property, @property-read, @property-write
• @property, @property-read, @property-write
• @property, @property-read, @property-write
• @return
• @see
• @since
• @source
• @subpackage
• @throws
• @todo
• @uses & @used-by
• @var
• @version

四、为什么我们需要注释

聊完了用法，我们来谈一下注释的必要性和重要性。

1. 代码首先是最好的注释

代码本身就在说明过程，比如优雅的变量名、方法名。

比如下面的这个方法，代码里不需要注释我们就知道写了什么。

    /**
     * Increment the counter for a given key for a given decay time.
     *
     * @param  string  $key
     * @param  int  $decaySeconds
     * @return int
     */
    public function hit($key, $decaySeconds = 60)
    {
        $this->cache->add(
            $key.':timer', $this->availableAt($decaySeconds), $decaySeconds
        );

        $added = $this->cache->add($key, 0, $decaySeconds);

        $hits = (int) $this->cache->increment($key);

        if (! $added && $hits == 1) {
            $this->cache->put($key, 1, $decaySeconds);
        }

        return $hits;
    }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

2. 注释可能没有跟随代码变更

比如，一项业务比较复杂，你写了一段注释。

//当A的状态变成2时，对B进行批量修改
1

但是，有个版本对业务做出的了更新，导致实际代码的内容变了。

//当A的状态变成2时，对B进行批量修改
if($a->status == 2 && $h == 3){
}
1
2
3

这样问题就出现了，自己和队友不知道信任哪个，所以需要花时间去找原型问产品经理。

不知不觉这样下去，团队的效率就降低了。

3. 必要并且不繁琐的注释才是好注释

必要并且不繁琐意味着：

• 不对简单的赋值语句进行注释
• 仅对一眼看不到上下文的业务进行多行注释
• 对封装复杂的方法进行注释

五、总结

这次我们学习了PHP中注释的用法，以及PHPDoc中的注释标准，最后我们学习了如何写优美的注释。

如果你有疑问，欢迎在评论区留言，如果你有问题，欢迎在我的社区中发帖，地址是 https://bbs.csdn.net/forums/metalyoung?spm=1001.2014.3001.6682&typeId=121629 。