C语言编程 1.5 关于注释的见解（附例子）

一个认为一切根源都是“自己不够强”的INTJ

个人主页：用哲学编程-CSDN博客
专栏：C语言编程

在编码的海洋中，注释是导航的灯塔，指引着未来的探索者和维护者。然而，注释的艺术往往被低估，它的真正价值在于如何将代码的灵魂展现给读者。以下是我对编写代码注释的一些见解，欢迎大家补充：

1. 假设读者已经熟悉这门语言：你不需要教读者如何编程。不要解释语言的显而易见的特性。你需要解释的是代码中不明显的部分。

2. 使用完整的句子进行注释，并使用正确的大小写和标点符号：注释不是代码。它们是你写给自己或其他代码读者的话。如果遵循这一准则，你的注释将不那么神秘且更易于理解。

3. 注释语言的不寻常用法：每种语言都有其奇怪之处和特殊性，这些可能不经常使用或以意想不到的方式使用。这些应该被澄清和突出。

   # 注意：Python中的列表推导式可以嵌套，但这种用法并不常见，且可能导致代码难以阅读。
   # 以下代码展示了如何使用嵌套列表推导式来生成一个由元组组成的列表，每个元组包含两个随机数。
   # 这种用法在处理复杂的数据转换时可能有用，但应谨慎使用，以免降低代码的可读性。
   import random
   nested_list_comp = [(random.randint(1, 100), random.randint(1, 100)) for _ in range(5) for _ in range(3)]
   

4. 尝试以对代码变更有弹性的方式进行注释：很多时候，随着代码的变更，注释不一定会相应更新。缓解这一问题的一个方法是在函数开始部分或代码块前用注释块，而不是将注释散布在代码块中。这样如果那些代码块发生变化，注释仍然有效。

   # 函数功能：对输入数据进行预处理，以便进行机器学习模型的训练。
   # 参数：data - 原始数据集，包含多个特征和标签。
   # 返回值：预处理后的数据集，特征和标签分离。
   # 预处理步骤包括：
   # 1. 数据清洗：去除缺失值和异常值。
   # 2. 特征缩放：对数值型特征进行标准化。
   # 3. 编码转换：对类别型特征进行独热编码。
   # 4. 数据分割：将数据集分为特征矩阵和标签向量。
   def preprocess_data(data):
       # 数据清洗...
       # 特征缩放...
       # 编码转换...
       # 数据分割...
       return features, labels
   

5. 从高层次进行注释：描述代码的意图和它尝试解决问题的方式。这一准则与我们之前提到的第一条准则相辅相成。注释描述的层次越高，随着代码的变更，注释需要更改的可能性就越小。

   # 模块名称：用户认证模块
   # 模块功能：提供用户登录、注册和权限验证的功能。
   # 设计理念：采用JWT（JSON Web Tokens）进行用户身份验证，确保安全性。
   # 使用说明：
   # 1. 用户注册：调用register_user函数，传入用户名和密码。
   # 2. 用户登录：调用login_user函数，传入用户名和密码，获取JWT令牌。
   # 3. 权限验证：在需要验证用户权限的API中，使用verify_token函数验证JWT令牌。
   # 维护者：Jane Smith
   # 联系方式：jane.smith@example.com
   

6. 传达你的意图：通过你的注释，努力传达你正在写的代码的意图，为什么需要这段代码，以及这段代码试图完成什么。代码实际在做什么应该通过代码本身来表达。

   # 函数功能：实现一个简单的缓存机制，以减少对数据库的频繁查询。
   # 设计意图：通过在内存中存储最近查询的结果，提高系统的响应速度和效率。
   # 参数：query - 查询字符串，用于从数据库中检索数据。
   # 返回值：查询结果，如果缓存中存在，则直接返回缓存数据；否则，查询数据库并更新缓存。
   # 注意事项：缓存大小有限，需要定期清理旧数据以避免内存溢出。
   def cached_query(query):
       # 检查缓存...
       # 如果缓存命中，返回缓存数据...
       # 如果缓存未命中，查询数据库并更新缓存...
       return result
   

   本节内容到此结束！！感谢阅读！