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：执行垃圾网络操纵。* / 
} 

（编辑：湖南网）

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