前言

代码是否应该写注释，现在大概有两种看法。第一种以为，优异的代码不需求注释，即很多人推重的代码即注释；第二种以为，写代码应该要写注释。

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

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

咱们先考虑下，代码即注释的观念是否正确。关于代码即注释，主要有两个好处。
其一是在不写注释的状况下，避免了必定的工作量，这个工作量包括注释的编写，保护以及注释标准的保持。在实际工作中，咱们都遇到过注释和实际代码目的不一致的状况，这就是注释没有保护好，为代码的保护造成更多的负担。
比如下面这个常常用来被调侃的比如

<?php
/** 获取明日这个时候的时刻戳.
/*
/* @return int 时刻戳.
*/
function getTomorrowTime()
{
    sleep(86400);
    return time();
}

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

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

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

  1. 当代码中，需求发送一个事件时，有人喜爱用dispatch，有人喜爱用send。
  2. 转换成布尔值，有人喜爱 (bool) $var，有人则会用 !!$var
  3. 参阅以下代码片段
<?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 都是保证代码质量(包括代码和注释本身)的重要东西。