3.注释

关键思想

注释的目的是尽量帮助读者了解和作者一样多

3.1 了解什么不需要注释

​ 对于大多数程序员,知道哪些不需要注释比知道注释要难得多。

​ 阅读注释会占用阅读真实代码的时间,并且每条注释都会占用屏幕上的空间,我一直强调屏幕是不可再生资源,且行且珍惜。那么,它就应该是物有所值。那莪如何分辨什么是好的注释,什么是没有价值的注释?

  • 不要为那些从代码本身就能快速推断的事实写注释
//初始化一个socket
fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP)

​ 从技术来讲,这里的注释也没有表达任何“新信息”,如果阅读代码本身,你就能明白它到底在做什么,这段注释就是不需要的。

  • 不要为了注释而注释

    不要因为没有对没有注释的函数拥有负罪感。

  • 不要给不好的名字加注释——应该把名字改好

    注释不应该粉饰不好的名字,一个好的名字比一个好的注释更重要。

    通常来讲,你不需要“拐杖式注释”——试图粉饰可读性差的代码的注释都是愚蠢的。写代码的人常常把这条规则表述成:好代码 > 坏代码 + 好注释

3.2 记录你的思想

现在你知道了什么不需要注释,下面讨论什么需要注释,很好的注释仅通过 “记录你的想法”就能得到,也就是你在写代码时有过的重要的想法。

  • 加入“导演评论”

    你应该在你的代码中加入 注释来记录你对代码有价值的见解,也就是写一些有价值的评论,下面是一个例子

// 出乎意料的是,对于这些数据用二叉树比用哈希表快40%
// 哈希运算的代价比左/右比较大得多
  • 为代码中的瑕疵写注释

    代码始终在演进的过程中,并且在这个过程中肯定会有瑕疵。不要不好一次把瑕疵记录下来。

    例如,当代码需要改进的时候

    // TODO: 采用更快的算法
    

    有几种标记在程序员中很流行

    流行的注释标记
    Figure: 流行的注释标记
  • 给常量加注释

    当定义常量时,通常在常量的背后都有着关于它是什么或者为什么是这个值的"故事",通过加注释可以告诉读者这个值的调整指南.

3.3 不要把注释放在一个函数体内部

​ 如果函数复杂到你需要独立的注释其中的一部分,那就是你的代码的写的有问题,回到函数那一部分,不要想着为坏代码写注释,应该放更多的精力写好的代码。

​ 你可以做一些小注释来注明或警告某些很聪明(或者槽糕)的做法,但不要加 太多。你应该做的,是把注释放在函数的头部,告诉⼈们它做了什么,也可以加上它做这些事情的原因

长行注释的首选风格是:

/*
* This is the preferred style for multi-line
* comments in the Linux kernel source code.
* Please use it consistently.
*
* Description: A column of asterisks on the left side,
* with beginning and ending almost-blank lines.
*/

results matching ""

    No results matching ""