你不需要注释

最新推荐文章于 2022-11-13 20:15:03 发布

kavenGw

最新推荐文章于 2022-11-13 20:15:03 发布

阅读量364

点赞数

分类专栏：随笔

随笔专栏收录该内容

6 篇文章

订阅专栏

本文探讨了过度依赖注释的危害，提出通过改进变量命名、重构代码等手段提高代码的自解释性，从而减少不必要的注释。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

翻译自The Knights of Unity

看到一篇好文章，索性练练自己的英语。不过还是要提前申明一下我并不主张完全不写注释，在前年的时候，将一个项目交接给别人，然后去年又回去接手这个项目，发现被改的面目全非，而且非常多bug。同事告诉我被改的原因是没有注释，看不懂。但是当我接手时却发现现在的注释还远不如我当初。在我看来，一个好的项目需要时间，而很可能你在项目前期需要更多的进度，很难做到尽善尽美，因此一些注释是不可避免的。但是正如这篇文章所说的，并不需要太多的注释，尤其在你的代码写的很好的情况下。

如果你是一个Unity的开发者，那你很可能需要写代码，除非你使用Playmaker或者别的相似的工具。作为一个程序员，你很可能想要让你的代码尽可能的阅读行强，因为你不久之后或者马上就要思考你为什么会用这个方式。如果你是通过注释来让你的代码阅读性更强，那么你很可能错了。

为什么注释不好

你很可能觉得我是一个理想主义者，想用冲突，宗教的一些词来形容我，但是这并没有什么关系。每行代码需要或多或少的注释，但是在大多数情况下，当你想写注释的时候，你几乎都有更好的办法。

代码很容易过时

思考这段代码

void Update(){
    //finish level after 60 seconds
    if(Time.timeSinceLevelLoad >= 60){
    }
}

假设某人改成这样

public float PlayTime = 120;
void Update(){
    if(Time.timeSinceLevelLoad >= PlayTime){
    }
}

如果某人将PlayTime从60秒改成了120秒，这就是一个常见的注释错误。即便这个注释可能也会被修改，但是任何修改PlayTime的人不会关心Update函数的注释现在已经对我们撒谎了。

注释需要和代码一起阅读

注释存在的目的难道不就是为了和代码一起阅读吗？但是如果代码的旁边有注释那么读代码的人不就需要更多的时间来阅读因为他说她需要分析代码和所有的注释。只有阅读者在理解代码的注释后才能理解代码，所以这消耗的2倍的时间来理解。

现在我想告诉你一些真实的场景下注释该如何使用。

使用更准确的变量名字

如此显而易见的事却竟然被忽略。你是否经常使用a,b,x2…etc作为变量名。

//计算自己和敌人的距离
float a = Vector3.Distance(p1.transform.position,en.transform.position);
//如果足够近
if(a < 100){

}

首先你需要知道一点，使用短的变量名不会让你的程序更快，只会让你的代码的可读性变差，永远要记得使用更准确地变量名。当然，这并不是说让你使用尽可能长的变量名，所以如果你可以使用简写的变量名，但是确保它很容易被理解。(pointer->ptr,texture -> tex).使用太长的变量名会让你的代码变得臃肿，因此你不得不做出妥协。

float playerToEnemyDist = Vector3.Distance(player.tranform.position,enemy.transform.position);

注意到我们不再需要计算自己和敌人的距离这段注释因为playerToEnemyDist足够告诉我们它在做什么。

不要直接使用数字未变量赋值

直接为数字为变量赋值可能会让人很难理解为什么会是这个值，而应该被先定义成变量或者常量，并且有一个准确的变量名

private static const float EnemyAttackDistance = 100;

void Update(){
    ...
    if(playerToEnemyDist < EnemyAttackDistance)
    ...
}

不要解释if

如果你有一段if语句，而你不知道它做什么或者为什么要加上这个判断，你可能想要为这个语句写一个注释。但是在你做之前，应该将条件提取到一个具有准备意义函数名字的函数中

void Update(){
        if(EnemyIsNearPlaayer()){
    ... 
}
}

bool EnemyIsNearPlayer(){
    float playerToEnemyDist = Vector3.Distance(player.tranform.position,enemy.transform.position);
    return playerToEnemyDist < EnemyAttackDistance;
}

留意函数参数

观察这段代码

//attack the player with claws or poison as secondary attack
enemy.Attack(player,Attack.Claws,Attack.Poison)

如果中毒伤害是二段伤害，那你就需要通过注释来说明，这也是注释有用的真实场景之一。但是你为什么不考虑使用结构体而不是原始参数。

public struct AttackInfo{
    public Attack Primary;
    public Attack Secondary;
}

void Attack(Character player,AttackInfo){

}

enemy.Attack(player,new AttackInfo{
    primary = Attacks.Claws,Secondary = Attack.Poison;
})