趣谈代码中的注释

代码注释应该算是最具争议的话题之一了。每当程序员们讨论这个话题，可谓是公有公理，婆有婆理。

该不该写注释

四位不同风格的程序员进行了一场辩论，他们分别是唐僧、悟空、八戒、沙僧。

唐僧：自项目成立三年以来，我时常听到大家对注释的争论和抱怨，今天我们就在此讨论讨论吧，这有助于我们顺利修成正果。

八戒：没错，我建议我们给项目加个注释标准。猴哥写的代码从来都没注释，有些代码读起来老费劲儿了！

悟空：你这呆子比我想象的还要没经验。把注释当成灵丹妙药了吧。有经验的人都知道，注释反而会让代码更难读懂。因为自然语言没法像计算机语言那样精确，注释里就会有一大堆废话和歧义。要是代码本身就不清晰，那注释写得再好也没用。而且，一改代码注释就过时了，这种情况经常见。要是我相信你的注释，那我可就倒霉了。

沙僧：师兄们别着急，听我说。如果滥用注释，反而会增加阅读量，适得其反。但是如果注释用得好，就会事半功倍。我既维护过有注释的代码，也维护过没注释的代码，我还是更愿意维护有注释的代码。

八戒：就是嘛！要是注释没用，那么多人为啥还写呢？我扫一眼注释就能找到要修改的地方，比看几十行代码省事多了。你不写注释，我猜有几个原因：一是你觉得自己的代码已经清晰到极致，二是你总觉得别人对你的代码充满浓厚的兴趣，三是你过高估计了别人的智商，四是你就是懒。

悟空：我是高估了你的智商，你写的代码简直就是业界良心，几乎每行都有注释，只不过是在啰嗦地重复一遍代码而已，没啥用。我追求的是写出清晰易懂的代码，我的代码都是自我解释的，对吧沙师弟？

沙僧：大师兄，我并不是说你的代码不清晰，我经常阅读你的代码，你的确写得很好很清晰。但是在我们平时的代码审查中，你经常被问到 “你这段代码是干嘛用的？”。所以，你还是多写点注释吧，心怀慈悲地为大家考虑一下。
（悟空认为自己的代码自我解释，但在别人看来好像并不完全是这样）

唐僧：悟空，你说你的代码已经能够自我解释，这确实是一个很好的目标。但我们要考虑到其他团队成员或未来维护代码的人可能会遇到理解上的挑战。如果注释能够提供额外的上下文信息或解释复杂的逻辑，那将有助于团队更好地理解代码。就算是我们自己过一段时间再回头看自己写的代码，也会有很多难以理解的地方。而且，如果我们接手一个新项目，往往也不清楚应该把某些功能放在哪个模块，或者是应该往 xxxApiService 还是 xxxApiClient 里添加新的 API 请求。这时候，如果文件顶部有个简明扼要的注释说明一下，那就再好不过了。看小说或者讲故事的时候或许不看章节标题也能理解，但是看技术类的书籍，我们可是期望能快速找到自己想看的部分，阅读代码也一样。

沙僧：师傅说得对，写注释能够让大家更容易理解代码在干嘛。提纲挈领的注释，能帮助大家迅速准确地理解一个类的职责和功能。

唐僧：我们要提倡加注释，但也不能滥用注释，代码自我解释是我们的追求，不过恰到好处的注释也是必不可少的。注释应该简明扼要、清晰易懂，并随着代码的变化及时更新。我们的最终目标都是提高代码的可读性。

悟空：师傅，您说的 “恰到好处” 就像是 “盐少许” 一样，那我们该如何把握呢？

唐僧：阿弥陀佛，这个问题问得好。关于如何写好注释，我们很难制定一个统一的标准，要求大家都按照某种特定的方式来写注释。但是，有一些原则我们可以遵循。

如何写好注释

六种注释分类：

概述性注释：概述性注释用于提供代码或函数的总体介绍和概述。它们通常位于代码的开头或函数的定义之前，描述代码的目的、功能和用途。
这是著名 IOS 网路请求框架 Alamofire 中 Session.sift 的一个例子：

import Foundation

/// `Session` creates and manages Alamofire's `Request` types during their lifetimes. It also provides common
/// functionality for all `Request`s, including queuing, interception, trust management, redirect handling, and response
/// cache handling.
open class Session {
	//...
}

行内注释：行内注释是在代码行旁边或同一行上的注释。它们用于解释特定代码行的含义、目的或实现细节。行内注释应该简洁明了，不占用过多空间。
示例：

function validateEmail(email: string): boolean {
    // Regular expression pattern for email validation
    const emailPattern = /^[\w-]+(\.[\w-]+)*@([\w-]+\.)+[a-zA-Z]{2,7}$/;
    return emailPattern.test(email);
}

块注释：块注释是多行注释，用于解释一段代码的功能、算法、复杂逻辑或相关的业务规则。块注释通常位于代码块的上方，并使用特定的注释符号或标记来界定。

// Divide result by two, taking into account that x
// contains the carry from the add.
for (int i = 0; i < result->size(); i++) {
   x = (x << 8) + (*result)[i];
   (*result)[i] = x >> 1;
   x &= 1;
}

文档注释：文档注释用于生成代码文档和API文档。它们通常使用特定的文档注释格式，如Java中的Javadoc或Python中的Docstrings。文档注释提供了对函数、类和模块的详细说明，包括参数、返回值、用法示例等。
TODO注释：TODO注释用于标记需要完成或修复的任务。它们通常用于暂时放置一些待办事项，以便在后续的开发中追踪和处理。

// @TODO: need to check if we can move to the main switch
if (action === CLAIM_ACTION.UPDATE) {
    handleOnClaimSuccess(originalLead, navigate);
    return;
}

废弃代码注释：废弃代码注释用于标记已弃用或不建议使用的代码或函数。它们提醒开发人员不要使用这些代码，以防止不必要的使用或错误。

/**
 * @deprecated This function is deprecated and will be removed in future versions.
 * Please use the new calculateTotal() function instead.
 */
function calculateSum(a: number, b: number): number {
  return a + b;
}

十个原则：

注释目标明确：注释应该有明确的目标和目的。它们应该提供额外的上下文信息、解释复杂的逻辑或强调特殊的业务规则。避免无关或重复的注释。

简明扼要：注释应该简洁明了，用简洁的语言描述要点。避免冗长的注释，注重清晰度和可读性。

注释风格一致：制定一致的注释风格和格式，以便团队成员能够轻松阅读和理解注释。遵循所采用的编码规范或项目规范。

注释的时机：注释应在需要解释的地方提供必要的信息。避免过度注释，不要为每一行代码都添加注释，只注释关键和复杂部分。

注释的准确性：确保注释的准确性和与代码的一致性。注释应及时更新，以反映代码的变化。不准确的注释可能会误导他人。

避免废弃注释：删除过时或不再需要的注释，以保持注释的有效性。过多的废弃注释会增加阅读和理解代码的困惑。

注释的语言和表达：使用明确和清晰的语言，避免模棱两可或歧义的表达。避免使用专业术语或行业特定的缩写，除非它们是广为接受和理解的。

注释和代码一致：注释应与代码保持一致，不要产生冲突或误导。维护注释与代码的一致性是非常重要的。

上下文和解释性注释：在需要的地方提供必要的上下文信息，解释代码的意图和行为。对于复杂的算法或逻辑，提供适量的解释，以帮助读者理解。

使用工具辅助：使用适当的工具来生成文档和注释。一些代码编辑器和IDE提供自动生成注释的功能，可以减少手动编写注释的工作量。

总结

关于代码注释的争论可以说是无休止的，每个人都有自己的观点和偏好。在这场辩论中，唐僧、悟空、八戒和沙僧代表了不同的立场和观点。

悟空可能确实阅读了《代码整洁之道》，但唐僧的总结观点更容易被大众接受。根据《代码整洁之道》的理念，注释被认为是一种不得已的做法，用来弥补代码表达能力的不足。如果代码能够清晰地表达意图，就没有必要写注释。我认同这个观点的方向，但也认为其中存在一些过于绝对和理想化的成分。

尽管我们追求编写能够自我解释的代码，但在现实情况中，总会遇到一些复杂的业务规则、算法或特殊情况。在这些情况下，注释可以提供必要的解释和说明，有助于其他人更好地理解和修改代码。

因此，我认为注释的使用应该具有灵活性和适度性。我们应该努力编写清晰易懂的代码，减少对注释的依赖，但也要意识到在某些情况下注释是必要且有价值的。