Redis是如何写代码注释的？

教学注释不会试图解释代码本身或我们应该注意的某些副作用。教学注释教授的是代码运行的“领域”(例如数学，计算机图形学，网络系统，统计，复杂的数据结构等)，这些信息可能超出了读者的认知范围，或者细节多到难以回忆。

版本5中的LOLWUT命令需要在屏幕上显示旋转的方块。为了做到这一点，它使用了一些基本的三角函数：尽管涉及的数学内容很简单，但许多阅读Redis源代码的程序员可能没有任何数学背景知识，因此函数顶部的注释解释了该函数的原理。

/* 
* 绘制一个以指定的x，y坐标为中心的正方形 
* 旋转角度和大小已定。为了写出旋转方块的代码，我们使用了 
* 参数方程： 
* 
* x = sin（k） 
* y = cos（k） 
* 
* 绘制一个圆（0-2*PI）。然后，如果我们从45度 
* 开始，即k = PI / 4，以此作为第一个点，然后我们发现 
* 其他三个点的K值以PI / 2（90度）递增，于是我们得到 
* 了构成一个圆的点。为了旋转方块，我们从 
* k = PI / 4 + rotation_angle开始，然后我们就完事儿了。 
* ...... 
* / 

注释不包含任何与函数本身的代码，或其副作用，或与函数相关的技术细节等内容。注释描述的部分仅限于函数内部使用以达到给定目标的数学概念。

清单注释

这是一个非常常见且奇怪的问题：有时由于语言限制，设计问题，或者仅仅因为系统内部固有的复杂性，我们无法将某个概念或界面集中在一个代码片段中，因此代码中有一些部分能提醒你在代码的某个部分做某件事。一般概念是：

/ * 警告：如果你在此处添加类型ID，请务必修改 
 
   * getTypeNameByID（）函数。* / 

在一个完美世界中，我们永远不需要添加这类注释;但在实践中有时没法省略这一步。

在这种情况下，防御性注释有时能起作用：如果你修改了某节代码，它会提醒你修改代码的其他相关部分。具体而言，清单注释会发挥以下一种作用(或者两种兼而有之)：

* 告诉你在修改某些内容时要执行的一系列操作。

* 警告你应该如何进行某些更改。

引导注释

我滥用引导注释到这种程度：Redis中的大多数注释都是引导注释。然而，引导注释正是大多数人认知中那类完全无用的注释：

* 他们没有说明代码中不甚明了的内容。

* 指导注释不提供有关设计方面的提示。

引导注释只做了一件事：他们照顾了读者的需求，在读者处理源代码中的内容时提供明确的划分(division)和节奏(rhythm)，并介绍接下来需要阅读的内容。

rax.c

/ *调用节点回调（如果有的话），如果回调返回true 
  *则替换节点指标* / 
if (it->node_cb && it->node_cb(&it->node)) 
    memcpy(cp,&it->node,sizeof(it->node)); 
 
/*对于“下一步”，每次找到一个键就停止 
*一次，因为相比较后面子节点分支中的内容 
*键本身字典序较小。* / 
if (it->node->iskey) { 
    it->data = raxGetData(it->node); 
    return 1; 
} 

Redis内“实际上”充满了引导注释，所以基本上你打开的每个文件都会包含很多引导注释。为什么要费这个力气呢?在这篇博客文章中所分析的所有注释类型中，这绝对是最主观的一种。我并不觉得没有引导注释的代码就不是好代码。但我坚信，如果人们认为Redis代码是可读的，部分原因就在于其中的引导注释。

引导注释还有一些别的用处。因为它们明确地将代码划分为独立的部分，所以我们能在合适的位置插入新代码，而不是随便加在其他代码后面。在代码附近设置相关语句能大大提高可读性。

引导注释能简要地告诉读者函数将要执行什么操作，所以如果你只对大框架感兴趣，则无需回过头去阅读函数。

琐碎注释

引导注释是非常主观的工具。不管你喜不喜欢，我反正超爱引导注释。

然而，引导注释可能会退化为极其糟糕的注释：它很容易变成“琐碎注释”(trivial comment)。

琐碎注释这种引导注释所带来的认知负荷和仅阅读相关代码比起来相差无几，甚至可能更高。以下这种琐碎注释正是许多书籍规劝你避免的。

array_len ++; / *增加数组的长度。* /

因此，如果你写引导注释的话，，请避免写琐碎注释。

(代码)负债注释

负债注释是源代码内部硬编码的技术债务语句：

entries -= to_delete; 
marked_deleted += to_delete; 
if (entries + marked_deleted > 10 && marked_deleted > entries/2) {     
  / * TODO：执行垃圾收集操作。* / 
} 

（编辑：核心网）

【声明】本站内容均来自网络，其相关言论仅代表作者个人观点，不代表本站立场。若无意侵犯到您的权利，请及时与联系站长删除相关内容!