Redis是如何写代码注释的？

很多人以为，假如代码写得足够踏实，注释就没什么用了。在他们看来，当统统都计划妥其时，代码自己会记录其浸染，因此代码注释是多余的。我对此持差异意见，首要出于两个缘故起因：

1、很多注释并未起到表明代码的浸染。

2、注释使读者不必凭梦想象太多细枝小节，辅佐读者低落认知承担。

注释的分类

我的事变始于随机地阅读Redis源代码，以搜查注释是否以及为什么在差异的上下文中起浸染。我很快发明，注释的浸染来历于多方面：它们在成果，编程气魄沤背同长度和更新频率方面每每很是差异。我最终转向了注释分类。

在研究时代，我确定了九种注释种别：

* 函数注释 Function comments

* 计划注释 Design comments

* 缘故起因注释 Why comments

* 解说注释 Teacher comments

* 清单注释 Checklist comments

* 引导注释 Guide comments

* 噜苏注释 Trivial comments

* (代码)欠债注释 Debt comments

* 备份注释 Backup comments

在我看来，前六个首要长短常起劲的注释情势，而最后三个有点值得猜疑。在接下来的部门中，我将行使Redis源代码中的示例说明每种注释范例。

函数注释

函数注释的方针是防备读者直接阅读代码。

在阅读注释之后，读者应该可以将一些代码视为应遵守某些法则的黑箱子。凡是环境下，函数注释位于函数界说的顶部。

rax.c：

/ * 在当前节点的子树中探求最大的key。 
    假如内存不敷返回0，不然 返回1. * / 
int raxSeekGreatest（raxIterator * it）{ 
    ... 
} 

函数注释现实上是一种内联API文档。假如函数注释编写得好，那么用户在大大都时辰能跳回到她正在阅读的内容(如阅读挪用此类API的代码)，而无需阅读函数(function)，类(class)，宏(macro)等的实现进程。

在全部注释范例中，函数注释被整个编程界普及接管和必要。要说明的独逐一点是：在代码内部安排以API参考文档为主的注释是否是件功德。

对我来说谜底很简朴：我但愿API文档与代码完全匹配。跟着代码的变动，文档也获得变动。出于这个缘故起因，我们将函数注释用作函数或其他元素的序言，使API文档靠近代码，完成三个使命：

* 跟着代码的变动，我们可以轻松变动文档，API参考也不会有过期的风险。

* 这种要领使得变动者(理应是最清晰变动目标的人)在最大限度上成为API文档的变动者。

* 读者能通过阅读代码直接找到函数或要领(method)的文档，以便阅读代码的读者只存眷代码，而不是代码和文档之间的上下文切换。

计划注释

“函数注释”凡是位于函数的开头，而计划注释凡是位于文件的开头。

计划注释一样平常声名白给定代码片断行使某些算法、技能、能力和详细实现的方法和缘故起因，对代码中实现的内容举办了更高级此外概述。在这样的配景下，阅读代码会更简朴一些。

bio.c

*计划 
* ------ 
* 
*计划很简朴，我们用一个布局代表要执行的一项 Job 
*每种Job范例有差异的线程和Job行列。 
*每个线程都在守候行列中的新Job，并凭证次序处理赏罚 
*每个Job。 
 ... 

缘故起因注释

缘故起因注释表明白代码执行某些操纵的缘故起因——纵然代码执行的操纵很是明晰。请看以下来自Redis replication的代码 的示例。

replication.c：

if（idle> server.repl_backlog_time_limit）{ 
 
/* 当我们开释 backlog时，我们老是行使新的 
 * replication ID并破除ID2。这是 
 * 由于在没有backlog时，master_repl_offset 
 * 未更新，但我们仍会保存我们的 
 * replication ID，由此导致以下题目： 
 * 
 * 1.我们是一个主实例（master instance）。 
 * 2.我们的副本成为主处事器（Master）。repl-id-2将会 
 *   与我们的repl-id沟通。 
 * 3.我们作为主处事器，收到了一些更新呼吁，但不会 
 *   增进master_repl_offset。 
 * 4.稍后我们将酿成副本，毗连到新的 
 *   主处事器，它将接管我们第二个副本ID的 
 *   PSYNC哀求，但会稀有据纷歧致的环境 
 *   由于我们接管了写呼吁。* / 
 
changeReplicationId（）; 
clearReplicationId2（）; 
freeReplicationBacklog（）; 
serverLog(LL_NOTICE, 
    "Replication backlog freed after %d seconds " 
    "without connected replicas.", 
    (int) server.repl_backlog_time_limit); 
} 

假如我只搜查函数挪用，就没什么必要纠结的：假如超时了就变动主replication ID，破除帮助ID，最后开释replication backlog。

解说注释

（编辑：河北网）

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