每个开发者都会讨厌两件事情——阅读没有注释的代码和给代码写注释。虽然无注释的代码也许终不可得，但是审视我们的代码结构减少注释，那也是非常值得的。那么如何正确地给代码给注释呢？

本期话题
1、工作中你遇到过的糟糕注释或优秀注释有哪些？
2、你有什么可以减少注释，但依然能让他人看得懂代码的方法吗？

本期奖励：
截止2024年1月10日24时，参与本期话题讨论，将会选出5名幸运用户获得笔记本电脑包*1

幸运用户获奖规则：中奖楼层百分比为17%，32%、53%，76%、94%的有效留言用户可获得互动幸运奖。如:活动结束后，回复为100层，则获奖楼层为 100✖17%=17，依此类推，即第32、53、76、94位回答用户获奖。如遇非整数，则向后取整。如:回复楼层为84层，则84✖17%=14.28，则第15楼获奖。

未获得实物礼品的参与者将有机会获得 10-200 积分的奖励。

注:楼层需为有效回答(符合互动主题)，灌水/复制回答将自动顺延至下一层。如有复制抄袭、不当言论等回答将不予发奖。阿里云开发者社区有权对回答进行删除。获奖名单将于活动结束后5个工作日内公布，奖品将于7个工作日内进行发放,节假日顺延。

以下为热心网友提供的参考意见

话题1

我来分享一下比较糟糕的代码注释：

• 注释过于冗长或过于复杂
• 注释提供了与代码本身无关的信息
• 注释缺乏详细的说明
• 代码过度依赖注释来解释自身的逻辑

话题2

1. 使用有意义的变量名：使用具有描述性的变量名可以帮助其他开发人员更轻松地理解代码。例如，使用“customerName”代替“cn”或“nm”。

2. 遵循代码风格指南：遵循代码风格指南可以使代码更易于阅读和理解，避免混淆和错误。例如，使用一致的缩进、命名约定和格式化规则。

3. 将代码拆分为函数和模块：将代码拆分为函数和模块可以提高代码的可重用性和可维护性，并使其更容易理解。每个函数应该只做一个特定的任务，且不超过一屏幕大小。

4. 使用注释来强调重要信息：在代码中使用注释来强调重要信息，例如算法的关键步骤、边界条件或复杂逻辑的解释。这可以提高代码的可读性，同时避免过多的注释。

5. 使用清晰的代码结构：使用清晰的代码结构可以使代码更易于理解和阅读。例如，使用空行将代码分成逻辑块，使用缩进将相关代码组合在一起。

以下为热心网友提供的参考意见

1. 使用有意义的变量和函数命名：选择清晰、具有描述性的变量和函数名称，可以减少对注释的需求。好的命名能够直接传达代码的意图和功能。

2. 模块化和函数化：将代码分解成小的、可重用的模块和函数。通过将代码分成逻辑块，可以使代码更易于理解，减少对注释的依赖。

3. 使用清晰的的代码结构：编写清晰、结构良好的代码，使其本身就能够传达其意图。例如，使用适当的缩进、空行和代码块来区分不同的逻辑部分。

4. 提供文档和说明：除了代码本身，提供额外的文档和说明也是减少注释的一种方法。可以编写项目级别的文档、API 文档或函数级别的注释，以解释代码的设计原理、用法和预期行为。

5. 使用类型系统和注释工具：某些编程语言和工具提供类型系统和注释工具，可以在代码中添加类型注释或文档注释。这些注释可以帮助他人更好地理解代码的意图和使用方式。

以下为热心网友提供的参考意见

1、工作中你遇到过的糟糕注释或优秀注释有哪些？
在维护代码时碰到的糟糕的注释有以下几类：

• 一大段文字，像是把需求内容拷贝过来的，不做精简，也没有对代码的逻辑进行归纳总结，让人看了感觉很费劲。
• 在没必要加注释的地方添加的注释，往往其他人一看就能明白的代码，这种注释有没有都可。
• 解释不够清晰的注释。在关键地方添加了注释，但是描述不清楚不完整，别人看了等于没看。
• 2、你有什么可以减少注释，但依然能让他人看得懂代码的方法吗？
• 方法的开头添加注释，描述方法的作用。
• 使用有效的英文名定义变量，避免使用中文拼音，这样可以使代码清晰，从而减少对变量的说明。
• 代码尽量结构清晰，避免重复使用变量，在关键步骤上添加代码说明。

以下为热心网友提供的参考意见

在工作中，我遇到过的糟糕注释和优秀注释具有显著的差异，下面我将给出一些具体的例子：

糟糕的注释示例：

1. 重复代码内容注释：

   // 计算两个数的和
   function add(a, b) {
     return a + b;
   }
   

   这种注释没有提供任何额外信息，因为函数名和代码逻辑已经足够清晰。

2. 过时或错误注释：
   “`java
   // 根据用户ID获取用户名，这个方法暂时无法处理异常，后续会修复
   String getUsername(int userId) {
   // … 实际上这个方法可能早已修复了异常处理问题，但注释未更新
   }

3. 废话注释：

   # 开始循环（遍历数组）
   for item in my_list:
       ...
   

优秀的注释示例：

1. 解释意图与目的：

   // 计算并返回用户购物车中所有商品的小计金额，已考虑优惠券折扣
   function calculateSubtotal(cartItems, couponDiscount) {
     ...
   }
   

2. 复杂逻辑说明：
   “`java
   // 使用迪杰斯特拉算法计算图中从节点A到节点B的最短路径
   // 参数graph是一个邻接矩阵表示的无向有权图
   List dijkstra(Node startNode, Node endNode, int[][] graph) {
   …
   }

3. 异常情况提示：

   # 获取用户信息，若用户不存在，则返回None而不是抛出异常
   def get_user_info(user_id: int) -> Optional[User]:
       ...
   

4. 修改记录和版本变更：

   // 2022-06-01 修改：增加对负数输入的支持，之前的版本只支持正整数。
   int CalculateSquareRoot(int number) {
     ...
   }
   

总结来说，好的注释应该阐明代码的目的、使用场景、复杂逻辑以及重要的设计决策，而非简单地重复代码本身的内容。同时，注释应当随着代码的迭代更新而及时维护。

以下为热心网友提供的参考意见

1、工作中我遇到过的糟糕注释包括：

过于简单，几乎与代码重复的注释。例如：“i++”旁边的注释“增加i的值”。 过时的注释，与代码实现不再一致。这会导致读者误解代码的真正意图。 注释过于冗长，描述不够精炼。长篇大论的注释很难让人抓住重点，也不方便阅读。

优秀的注释则具备以下特点：

简洁明了，准确描述代码的功能或意图。 提供了必要的背景信息，帮助读者理解代码的工作原理。 与代码保持同步，及时更新注释，以确保其准确性。

2、为了减少注释，同时确保代码的可读性，我有以下建议：

命名变量和函数时，尽量选择有意义的名称，这样可以减少对注释的依赖。 使用有意义的代码结构，将复杂的逻辑或算法分解为更小、更易于理解的模块或函数。每个模块或函数应该有明确的输入和输出，以及清晰的文档说明。 利用代码的自解释性。通过合理的缩进、排版以及使用有意义的变量名，可以使代码更容易阅读和理解，从而减少对注释的需求。 编写单元测试和集成测试，通过测试用例来解释代码的功能和行为。这有助于他人理解代码的工作原理，而无需过多注释。 培训团队成员，提高他们的代码阅读和理解能力。一个经验丰富的开发者应该能够快速理解代码的意图和功能，而不需要过多的注释。

以下为热心网友提供的参考意见

1、工作中你遇到过的糟糕注释或优秀注释有哪些？

我遇到的优秀注释就是每一个方法都有对应的思路及解释，每一个参数也都有对应的注释，基本上即便是第一次看，也能快速的上手.

2、你有什么可以减少注释，但依然能让他人看得懂代码的方法吗？

代码尽可能的模块化，每一个方法尽可能的做到单一切明了.

以下为热心网友提供的参考意见

工作中我遇到过的糟糕注释包括：

注释过于简单，没有提供足够的信息，例如只写了“初始化变量”这样一句话，但没有具体说明这个变量是什么，为什么要初始化。
注释与代码不一致，例如注释中说明了一个函数的功能，但实际上函数实现的功能与注释描述的不符。
注释过于冗长，写了一大堆无关紧要的信息，使得代码难以阅读。
工作中我遇到过的优秀注释包括：

注释详细说明了代码的功能、作用和实现方式，使得其他人能够快速理解代码。
注释对代码进行了必要的解释和说明，特别是在算法或逻辑比较复杂的地方，帮助阅读者更好地理解代码。
注释还包含了作者、修改日期等信息，使得代码的修改历史更加清晰。
2、为了减少注释，但依然能让他人看得懂代码，我有以下建议：

尽量使代码简洁明了，避免不必要的复杂度。
使用有意义的变量名、函数名等标识符，使代码更具可读性。
对于复杂的逻辑或算法，可以尝试将其拆分成多个函数或方法，并在主函数或方法中进行简单的调用和逻辑处理。这样可以使代码更加清晰易懂。
在代码中加入必要的注释，解释代码的作用、实现方式和注意事项等，但要避免过多的注释，保持代码的简洁性。
在编写代码时，可以尝试使用版本控制工具（如Git），记录每一次的修改历史，以便于其他人更好地理解代码。

以下为热心网友提供的参考意见

1、工作中你遇到过的糟糕注释或优秀注释有哪些？
工作中倒是没遇到过的太过于糟糕注释，就是有些注释太少，还是需要看代码。要不就是一些与当前代码不太符合的注释，这种情况比较少。
优秀的还是很多，我比较喜欢的一种就是，简单逻辑一嘴带过，复杂逻辑带有序号的每一步逻辑描述清晰就行。

2、你有什么可以减少注释，但依然能让他人看得懂代码的方法吗？
我常用的有两个：
首先，代码结构清晰，可读性提高，这样可以减少不必要的注释。
其次，命名规范，这样方法作用一目了然，不用太过于细读。
有时候复杂的也没啥好办法，时间久了，自己也忘。所以就标注好逻辑，加快阅读理解速度吧。

以下为热心网友提供的参考意见

在编写代码时，注释对于代码的可读性和维护性非常重要。然而，过多的注释可能会使代码显得冗长，降低代码的可读性。以下是几种可以减少注释但仍保持代码可读性的方法：

1. 使用有意义的变量名和函数/方法命名：通过使用清晰、有意义的命名，可以提高代码的可读性。好的命名可以传达代码的意图，并帮助他人更好地理解代码逻辑，从而减少对注释的依赖。

2. 模块化和函数/方法的划分：将代码划分为小的模块和函数/方法，每个函数/方法只处理一个具体的任务或逻辑。这样做有助于代码的结构清晰，使其易于阅读和理解。

3. 使用空格和缩进：适当的使用空格和缩进可以增加代码的可读性。通过正确缩进代码块和操作符，可以使代码结构更清晰，减少对注释的需求。

4. 添加文档字符串（Docstrings）：在函数/方法定义的开始位置添加文档字符串来描述函数/方法的用途、参数、返回值以及任何其他相关信息。这样做可以提供对函数/方法的说明，而不需要在代码中大量使用注释。

5. 使用命名约定：遵循常见的编码规范和命名约定，如PEP 8（Python的编码风格指南）等。这样做有助于提高代码的一致性和可读性，减少对注释的依赖。

6. 简化逻辑：在编写代码时，尽量保持逻辑简单明了。如果代码变得过于复杂，可以考虑重构或抽象出更小的函数/方法来处理独立的逻辑。这样可以减少注释，并使代码更易于理解。

注释是一个很有价值的工具，但过多的注释可能意味着代码本身不够清晰或可读。通过合理的命名、模块化、缩进和文档字符串等技巧，您可以减少对注释的需求，同时保持代码的可读性和可维护性。

以下为热心网友提供的参考意见

在编写代码时，注释的添加对于理解代码具有重要作用。首先，注释可以帮助他人理解你的代码以及你的想法。其次，注释应与代码相对应，当代码发生变化时，相应的注释也要及时更新。在注释的内容方面，高层次的注释（high-level comments）应该提供比代码更抽象的信息，比如代码的设计思路；而低层次的注释（low-level comments）应该提供比代码更详细的信息，如表示一个范围的两个参数是左闭右开还是左闭右闭。此外，避免写出与代码同一层次的注释，因为这往往就是重复的代码。注释的方式也值得注意，例如可以使用Doxygen格式的注释，特别是当一个类或函数体较大时，相关的注释可以帮助分解和理解各个部分。另外，避免直接将代码直译为注释，试图说明为什么要这样做通常会更有价值。最后，请确保为常量添加注释。虽然并非所有情况都需要注释，但在必要的情况下使用它们可以帮助维护和更新代码。总的来说，良好的注释习惯可以提高代码的可读性和可维护性。

以下为热心网友提供的参考意见

1.糟糕的注释：

是甲方公司购买的系统，1000多行没几行注释，代码又是03年的老项目，map获取字段，没有一个好的名字和规范。到处都是魔法值。一个离职流程回调中，就写了一个一句。离职流程回调开始。

2.正确的注释：

方法注释、说明该方法是什么功能，处理什么的

命名规范、尽量做到见名知意。

方法内代码段注释、没必要每一行是做什么都写注释，但是某一段做什么的可以说明。

不要秀技术、我记得去年还是前年的时候遇到了一个stream流写法的，整个方法里面从获取到数据后就开始了流式，一直到方法结束，平白无故的增加了代码的阅读难度

以下为热心网友提供的参考意见

1. 清晰的结构和命名：确保你的代码有清晰的结构，每个函数或模块都应该有明确的名称，并遵循一致的命名约定。这有助于读者理解代码的目的和功能。
2. 使用有意义的变量名：变量名应该清晰地描述它们代表的数据类型或值。避免使用过于简短的名称，因为这可能会使代码难以理解。
3. 使用有意义的函数和类名：函数和类的名称应该清楚地描述它们的功能。如果一个函数执行多个操作，考虑将其分解为更小的、更具体的函数。
4. 遵循一致的编程风格：选择一种编程风格并确保在整个代码库中保持一致。这包括缩进、空格、换行和注释的使用。一致的编程风格有助于提高代码的可读性。
5. 利用代码结构：通过使用条件语句、循环和函数调用等结构化元素，可以使代码更加清晰和易于理解。避免使用过多的嵌套语句和函数调用。
6. 利用数据结构和算法：选择合适的数据结构和算法可以简化代码并使其更易于理解。例如，使用列表、字典和集合等数据结构可以使代码更简洁。
7. 使用有意义的注释：虽然注释是必要的，但过度依赖注释可能会使代码难以维护。确保你的代码本身清晰明了，只在必要时添加注释。
8. 测试你的代码：确保你的代码在各种情况下都能正常工作，这样读者就可以直接看到结果，而无需花费时间理解代码的逻辑。
9. 提供文档：如果代码库很大或包含许多新成员，提供文档可能很有帮助。文档应该包含函数和类的说明、参数和返回值的描述，以及任何可能用到的特定库或框架的说明。

这些方法可以帮助减少注释，同时保持代码的可读性。但编写易于理解的代码是每个开发人员的责任，而不仅仅是某些人的工作。

以下为热心网友提供的参考意见

糟糕注释：
糟糕的注释通常会让人感到困惑，不能提供有价值的信息，或者与代码的实际意图不符。以下是一些糟糕注释的例子：

无意义的注释：例如，”这是一个注释”，这样的注释没有任何实际的帮助，只是浪费了读者的时间。
过时的注释：如果注释没有随着代码的更新而更新，那么它可能会误导读者。例如，一个关于已废弃功能的注释，但仍然存在，可能会让读者误以为该功能还在使用中。
复杂的注释：有些注释过于复杂，解释了太多的细节，使得读者很难快速理解。例如，一个注释详细描述了整个函数的逻辑，实际上读者可能只需要知道函数的作用和输入/输出即可。
优秀注释：
优秀的注释应该简洁、明确，有助于他人理解代码。以下是一些优秀注释的例子：

描述函数或变量作用的注释：例如，”此函数用于计算圆的面积”，或者”此变量用于存储用户名”。
对复杂逻辑的解释：对于难以理解的代码段，一个好的注释可以解释其背后的逻辑或思想。
对代码中使用的算法或技术的解释：这有助于读者理解代码中使用的技术或算法是如何工作的。
减少注释但仍然让他人理解代码的方法：
良好的命名习惯：使用有意义的变量名和函数名，可以使代码更容易理解，从而减少了对注释的依赖。
编写简洁的代码：尽量使代码简洁明了，避免冗余和复杂的逻辑，可以使代码更容易理解。
编写单元测试：通过编写单元测试，可以确保代码的正确性，并且测试用例本身就是一种解释代码如何工作的文档。
使用文档生成工具：有些编程语言有文档生成工具（如Python的Sphinx），可以自动从代码中提取注释和文档字符串，生成易于阅读的文档。

以下为热心网友提供的参考意见

1、在工作中，我遇到过一些糟糕的注释和一些优秀的注释。
在工作中，遇到糟糕的注释通常都是这样的：

• 没有注释或者注释非常简单，无法解释代码的逻辑或意图。
• 注释与代码不一致，导致误导或混淆。
• 注释中包含了无效的信息或已经过时的信息。
• 注释过于冗长、复杂或难以理解。
• 注释中含有拼写错误、语法错误或语言不清晰。
• 注释没有更新，导致与代码的实际逻辑不一致。
  而优秀的注释通常具备以下特点：
• 简洁明了，能够清晰表达代码的意图和逻辑。
• 注释与代码一致，不会给他人造成困惑或误导。
• 提供有用的补充信息，如代码的用途、关键参数、注意事项等。
• 使用规范的语法和拼写，避免造成误解。
• 及时更新，保持与代码一致。

2、减少注释但依然能让他人看得懂代码的方式有几种：

• 使用有意义的变量和函数名：通过给变量和函数取一个易于理解和表达其用途的名字，能够减少对注释的依赖。
• 模块化和良好的结构设计：通过将代码划分为合适的模块、函数或类，使得代码的逻辑结构更加清晰，减少对注释的需求。
• 编写自解释的代码：尽量让代码本身就能够表达其意图，而不是依赖于注释来解释。良好的代码组织和命名可以帮助实现这一点。
• 使用清晰的代码风格和约定：通过遵循一致的代码风格和约定，让代码更易于阅读和理解，从而减少对注释的需求。
• 添加必要的文档和说明：对于一些复杂或特殊的情况，可以编写必要的文档和说明，以便他人理解和使用代码。这些文档可以是独立的文档，也可以是内部或文档字符串的形式。
• 代码审查和知识分享：通过代码审查和团队内部的知识分享，能够帮助他人更好地理解代码，减少对注释的需求。

综上所述，通过选择恰当的变量和函数名、模块化设计、自解释的代码、清晰的代码风格、必要的文档和知识分享，我们可以减少对注释的依赖，同时依然能够让他人看得懂代码。

以下为热心网友提供的参考意见

1、工作中你遇到过的糟糕注释或优秀注释有哪些？
最糟糕的注释是没有注释，全凭经验和能力，浪费时间。
优秀的注释，在关键点会标注解释，涉及到变量做说明。
2、你有什么可以减少注释，但依然能让他人看得懂代码的方法吗？
养成写注释的习惯，将代码按功能进行模块化设计，做总的注释，在关键点再着重注释。

以下为热心网友提供的参考意见

1、糟糕的注释通常是没有提供实际有用的信息，或者是与代码不一致的注释。

比如，注释没有更新，导致与代码不符合，或者是使用了模糊的语言，难以理解。优秀的注释应该清晰明了，提供必要的信息，帮助他人理解代码的逻辑和目的。

2、减少注释的方法可以通过编写清晰、自解释的代码。使用有意义的变量和函数名，遵循良好的代码结构和设计模式，可以减少对注释的需求。

此外，编写自解释的代码也可以让他人更容易理解代码的逻辑。
使用有意义的命名：给变量、函数、类等命名时要尽量使用清晰、具有描述性的名称，避免使用含糊不清的缩写或简写。
模块化和组织结构：将代码模块化、组织结构清晰，采用良好的设计模式和架构，可以让代码更易于理解，减少对注释的依赖。
撰写清晰的文档：在需要解释复杂逻辑或算法的地方，可以采用文档的方式来说明，而不是在代码中添加大量注释。
使用自解释的代码：尽量编写自解释的代码，避免过于复杂的逻辑和嵌套，使代码本身就能清晰地表达其意图。
通过以上方法，可以减少对注释的依赖，让代码更易于理解和维护。

以下为热心网友提供的参考意见

糟糕的注释，Ctrl c+v来的代码，一点都不改，是一点都不能看。其实，把方法名写好，输入输出写清，基本上都能看得懂代码。

以下为热心网友提供的参考意见

1、我遇到过的糟糕注释主要有以下几种：

• 不清晰或误导性的注释：这些注释可能过于简略，没有提供足够的信息来理解代码的功能和目的，或者包含错误的信息，导致阅读者对代码的理解产生偏差。

• 过于冗长或重复的注释：有些注释可能会详细描述每一行代码的功能和实现细节，这不仅会增加代码的阅读负担，还可能导致注释和代码之间的不一致。

优秀的注释应该具有以下特点：

• 简洁明了：注释应该简洁地描述代码的功能和目的，避免使用复杂的术语和冗长的句子。

• 有价值和必要性：注释应该提供有用的信息，帮助阅读者理解代码的工作原理和设计决策，而不是仅仅重复代码的内容。

2、减少注释但依然能让他人看得懂代码的方法包括：

• 使用文档字符串和注解：在函数和类的定义中使用文档字符串和注解，可以提供详细的说明和参数信息，而不需要在代码中添加额外的注释。

• 编写测试用例和文档：通过编写自动化测试用例和用户文档，可以更全面地描述代码的行为和使用方法，而不需要在代码中添加过多的注释。

以下为热心网友提供的参考意见

1、工作中你遇到过的糟糕注释或优秀注释有哪些？

糟糕的注释通常表现为冗长、不准确或过时。例如，过于详细的注释，它们详细描述了代码的每个细节，而没有为读者提供有价值的见解或解释，这不仅没有帮助，反而增加了阅读的负担。另一种糟糕的情况是注释与代码的实际功能不一致，这会误导读者，使他们无法准确理解代码的功能。还有一种情况是注释未及时更新，与代码的实际功能和实现不再相符，这会导致读者得到错误的信息。

相反，优秀的注释通常简短明了，准确描述了代码的功能和意图。它们有针对性地解释了代码中的难点、关键点或实现细节，为读者提供了有意义的见解和解释。

2、你有什么可以减少注释，但依然能让他人看得懂代码的方法吗？

首先，选择描述性强、富有意义的变量名和函数名。这样，代码的意图和功能可以直接从名称中体现出来，减少了注释的必要性。

其次，保持一致的代码风格和格式。通过统一缩进、空格使用和代码布局，可以提高代码的可读性，减少注释需求。

另外，编写简洁而直接的代码段也很重要。通过编写结构清晰、逻辑直接的代码，可以减少注释的必要性，因为代码本身已经足够清晰。

利用文档字符串（docstrings）也是一个好方法。在关键函数和类定义处使用文档字符串，提供有关其功能和用途的简短说明，这有助于提高代码的可读性和可维护性。

以下为热心网友提供的参考意见

1、工作中你遇到过的糟糕注释或优秀注释有哪些？
2、你有什么可以减少注释，但依然能让他人看得懂代码的方法吗？

1、工作中我遇到过的糟糕注释包括：

过时的注释：注释没有随着代码的更新而更新，导致信息不准确。
不明确的注释：注释含糊不清，让人无法理解其含义。
冗长的注释：注释过于冗长，包含了大量不必要的信息。
与代码不匹配的注释：注释与代码实现不一致，导致混淆。
无用的注释：注释没有提供有价值的信息，只是占用了空间。
优秀注释则具备以下特点：
准确：注释准确地描述了代码的功能、意图和实现方式。
简洁：注释简明扼要，不冗长，不包含不必要的信息。
清晰：注释语言清晰，易于理解。
相关：注释与代码紧密相关，提供了有价值的信息。
更新：注释随着代码的更新而更新，保持信息的准确性。
2、为了减少注释但仍然让他人看懂代码，可以考虑以下方法：
编写清晰的代码：通过良好的变量命名、函数设计、模块划分等，使代码本身就能清晰地表达其功能和意图。
使用有意义的命名：为变量、函数、类等选择有意义的名称，可以使代码更易于理解，从而减少了对注释的依赖。
提取重复的代码：将重复的代码提取为函数或方法，并为其编写清晰的注释，可以提高代码的可读性和可维护性。
编写文档：为项目或模块编写文档，概述其功能、使用方法和注意事项。这样可以让其他人快速了解代码的目的和使用方式。
示例和演示：通过示例和演示来解释代码的功能和使用方法，可以使他人更好地理解代码的工作原理。