前言
代码是否应该写注释，目前大概有两种看法。第一种认为，优秀的代码不需要注释，即很多人推崇的 代码即注释 ；第二种认为，写代码应该要写注释。
在此，先给出结论： 代码需要注释 。但是不是每行都需要注释，或者需要多少注释，我们会在接下来的文章中讨论这个问题。（文中的例子均为PHP代码）
首先，我们先讨论下代码即注释 的问题。
我们先思考下，代码即注释的观点是否正确。对于代码即注释，主要有两个好处。 其一是在不写注释的情况下，避免了一定的工作量，这个工作量包含注释的编写，维护以及注释规范的保持。在实际工作中，我们都遇到过注释和实际代码意图不一致的情况，这就是注释没有维护好，为代码的维护造成更多的负担。 比如下面这个经常被用来被调侃的例子
<?php
/** 获取明天这个时候的时间戳.
/*
/* @return int 时间戳.
*/
function getTomorrowTime()
{
sleep(86400);
return time();
}
复制代码
其二是代码即注释，能提高团队的代码命名、可读性等。对于一个有强制代码风格检查、 Code Review 执行到位的团队来讲，推崇代码即注释，确实会强有力地推动代码的命名和可读性，提升编码能力。
从以上两点来讲，代码即注释的观念是正确的，也确实能给团队带来收获。但是，在团队实践代码即注释，也是有前置条件的。
首先，团队必须是相对固定的，这里的相对固定是指团队成员不会经常性流动。一个团队要达到代码即注释的水平，是很难的，即使你的团队是精英团队，每个人能力极强，但是大概率会有不同的技术背景，在认知上难免出现差异，这里举几个例子：
- 当代码中，需要发送一个事件时，有人喜欢用dispatch，有人喜欢用 send 。
- 转换成 布尔值 ，有人喜欢 ( bool ) $var，有人则会用 !!$var
- 参考以下代码片段
<?php
function test() {
if ($a > 0) {
return 100 / $a;
}
return 0;
}
// vs
function test() {
return $a > 0 ? 100 / $a : 0;
}
我们先不论谁好谁坏，这种不一致性是确实存在的。 要到达代码即注释，最重要的一点是你需要将团队成员的 编码 认知，基本拉到同一个水平，并且团队内部形成大家都认可的最佳实践。要做到这一点，需要团队长时间的协作和磨合。 对于一个流动性大的团队，是无法做到这一点的，假设团队5个人，刚把大家的认知统一，结果走了3个人；补充的3个新人，还得重新去拉齐大家认知，人员再流动，再拉齐，永远达不到目标。所以对于流动性极高的团队，老老实实写注释是最好的选择。
其次，你得有拉齐团队认知的工具和文化。比如严格的Code Review，自动化的代码风格检查等。一个Code Review 都做不好的团队，代码风格、逻辑实现千奇百怪，怎么能统一认知，怎么做到代码即注释呢。
总结一下，要在团队中实践代码即注释，首先得考虑团队的流动性、其次有没有相关工具和规范；对于一个新团队，即使有条件，也要长期坚持不懈推行规范，建立文化，才能得以成功。
最后，在谈谈代码即注释还有一个弊端，在一些特定的场景下，代码中会包含一些隐藏的逻辑，无法很好通过代码表达出来。对于不了解隐藏逻辑的人来说，往往会错误地使用该代码，造成Bug。
鉴于以上的原因，加上国内这种为抢占市场快速产出而导致遍地加班的环境，代码注释绝对是有必要的，至少试用于90%以上的团队。
代码注释写多少合适
对于这个问题，我们倾向于从三个情况考虑：
第一，你的团队是践行代码即注释的团队，并且做得还不错；对于这种情况，常规的代码注释可以省略，但是对于业务逻辑复杂或者包含隐藏逻辑的代码，这是需要注释的。
第二，你的团队有明确的注释规范；这种情况按团队规范来即可。
第三，你的团队没有良好代码的基因，不推崇代码即注释，也没有规范；这种情况下，团队负责人需要评估，是制定一套注释规范，还是践行代码即注释。我们的建议一般都是先制定注释规范，因为注释规范实现相对于代码即注释，时间和成本都要小很多；注释规范落地后，再考虑代码即注释的问题。
最后，不管是写注释还是践行代码即注释，Code Review 都是保证代码质量(包括代码和注释本身)的重要工具。
