| 【PHP】如何优雅地在PHP里写注释 | 您所在的位置：网站首页 › 注释里的URL › 【PHP】如何优雅地在PHP里写注释 |
【PHP】如何优雅地在PHP里写注释
|
目录
一、没有注释的代码就像是吃饭不给筷子二、PHP的注释方式1. 行内注释2. 多行注释
三、PHPDoc的注释1. PHPDoc是什么2. 注释的基本格式3. 完整的注释标签
四、为什么我们需要注释1. 代码首先是最好的注释2. 注释可能没有跟随代码变更3. 必要并且不繁琐的注释才是好注释
五、总结
一、没有注释的代码就像是吃饭不给筷子
你好，我是小雨青年，一名知道如何写注释的程序员。 注释，字面上的意思，就是解释性质的文字，而代码上的注释，说是一种艺术也不为过。 本篇内容你将会学到： PHP的注释格式以及应用范围如何规范注释 二、PHP的注释方式 1. 行内注释行内注释的作用是对单行代码进行注释，说明单行代码的作用。 $name = '小雨青年'; //给name赋值小雨青年上面仅作为注释的演示，实际项目中这样注释是无效并且拖沓的，不建议哦。 2. 多行注释多行注释一般用在需要写入大量换行文字上，比如复杂的业务说明和复杂的内部实现。 /* 多行注释的中间行不用带星号。 by 小雨青年 */目前这样的方式不常见了，IDE内的注释方式是每行带着星号的。 和下面的注释区分的是，多行注释的第一行带1个星号。 多行注释的内容和上下文不是强制关联，使用起来和单行注释一样随意。 三、PHPDoc的注释 1. PHPDoc是什么phpDocumentor 是 PHP 项目事实上的文档应用程序。 您的项目也可以从 20 多年的经验中受益，并为 PHP 应用程序文档设定标准。 简单来说，它是一个文档规范，目前的ide也是默认使用的。 下图是我从PHPStom的配置找到的相关配置，你可以根据自己的习惯或者团队的要求合理配置。
这是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; }我们可以看到如下特点 写在方法上面没有换行以/**作为开始第一行为对方法的说明@param为对应参数的说明，对应数据类型、参数名，后面还可以跟文字说明@return为返回值上面提到的，IDE对于PHPdoc格式的完全兼容，我们可以很方便看到注释，比如你在鼠标悬停的时候，就可以看到。
下面是所有的标签，点击可以查看官网的相关说明。 @api@author@category@copyright@deprecated@example@filesource@global@ignoreTag 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; } 2. 注释可能没有跟随代码变更比如，一项业务比较复杂，你写了一段注释。 //当A的状态变成2时，对B进行批量修改但是，有个版本对业务做出的了更新，导致实际代码的内容变了。 //当A的状态变成2时，对B进行批量修改 if($a->status == 2 && $h == 3){ }这样问题就出现了，自己和队友不知道信任哪个，所以需要花时间去找原型问产品经理。 不知不觉这样下去，团队的效率就降低了。 3. 必要并且不繁琐的注释才是好注释必要并且不繁琐意味着： 不对简单的赋值语句进行注释仅对一眼看不到上下文的业务进行多行注释对封装复杂的方法进行注释 五、总结这次我们学习了PHP中注释的用法，以及PHPDoc中的注释标准，最后我们学习了如何写优美的注释。 如果你有疑问，欢迎在评论区留言，如果你有问题，欢迎在我的社区中发帖，地址是 https://bbs.csdn.net/forums/metalyoung?spm=1001.2014.3001.6682&typeId=121629 。 |
【本文地址】