前言

代码是否应该写注释，目前大概有两种看法。第一种认为，优秀的代码不需要注释，即很多人推崇的代码即注释；第二种认为，写代码应该要写注释。

在此，先给出结论：代码需要注释。但是不是每行都需要注释，或者需要多少注释，我们会在接下来的文章中讨论这个问题。（文中的例子均为PHP代码）

首先，我们先讨论下代码即注释的问题。

我们先思考下，代码即注释的观点是否正确。对于代码即注释，主要有两个好处。其一是在不写注释的情况下，避免了一定的工作量，这个工作量包含注释的编写，维护以及注释规范的保持。在实际工作中，我们都遇到过注释和实际代码意图不一致的情况，这就是注释没有维护好，为代码的维护造成更多的负担。比如下面这个经常被用来被调侃的例子

<?php/** 获取明天这个时候的时间戳./*/* @return int 时间戳.*/function getTomorrowTime(){ sleep(86400); return time();}复制代码

其二是代码即注释，能提高团队的代码命名、可读性等。对于一个有强制代码风格检查、Code Review执行到位的团队来讲，推崇代码即注释，确实会强有力地推动代码的命名和可读性，提升编码能力。

从以上两点来讲，代码即注释的观念是正确的，也确实能给团队带来收获。但是，在团队实践代码即注释，也是有前置条件的。

首先，团队必须是相对固定的，这里的相对固定是指团队成员不会经常性流动。一个团队要达到代码即注释的水平，是很难的，即使你的团队是精英团队，每个人能力极强，但是大概率会有不同的技术背景，在认知上难免出现差异，这里举几个例子：

当代码中，需要发送一个事件时，有人喜欢用dispatch，有人喜欢用send。

转换成布尔值，有人喜欢 (bool) $var，有人则会用 !!$var

参考以下代码片段

0) { return 100 / $a; } return 0;}// vs function test() { return $a > 0 ? 100 / $a : 0;}

我们先不论谁好谁坏，这种不一致性是确实存在的。要到达代码即注释，最重要的一点是你需要将团队成员的编码认知，基本拉到同一个水平，并且团队内部形成大家都认可的最佳实践。要做到这一点，需要团队长时间的协作和磨合。对于一个流动性大的团队，是无法做到这一点的，假设团队5个人，刚把大家的认知统一，结果走了3个人；补充的3个新人，还得重新去拉齐大家认知，人员再流动，再拉齐，永远达不到目标。所以对于流动性极高的团队，老老实实写注释是最好的选择。

其次，你得有拉齐团队认知的工具和文化。比如严格的Code Review，自动化的代码风格检查等。一个Code Review 都做不好的团队，代码风格、逻辑实现千奇百怪，怎么能统一认知，怎么做到代码即注释呢。

总结一下，要在团队中实践代码即注释，首先得考虑团队的流动性、其次有没有相关工具和规范；对于一个新团队，即使有条件，也要长期坚持不懈推行规范，建立文化，才能得以成功。

最后，在谈谈代码即注释还有一个弊端，在一些特定的场景下，代码中会包含一些隐藏的逻辑，无法很好通过代码表达出来。对于不了解隐藏逻辑的人来说，往往会错误地使用该代码，造成Bug。

鉴于以上的原因，加上国内这种为抢占市场快速产出而导致遍地加班的环境，代码注释绝对是有必要的，至少使用90%以上的团队。