python_comment_guidelines

Python 代码注释规范

1. 引言

1.1. 注释的重要性

注释是源代码中用于解释代码功能、逻辑、目的或使用方法的说明性文本。良好的注释能够帮助开发者理解代码，减少维护成本，并促进团队成员之间的有效沟通。

1.2. 本规范的目标

本规范旨在为 Python 项目中的代码注释提供一套统一的指导原则和最佳实践，以确保注释的质量和一致性。 本规范是 Python 编码标准指南 中关于注释部分的详细阐述和补充。

2. 通用原则

2.1. 清晰性与简洁性

注释应当清晰、准确、简洁地表达其意图。避免使用含糊不清或过于冗长的描述。

2.2. 与代码同步

注释必须与它所描述的代码保持同步。当代码发生变更时，相关的注释也应立即更新。过时或错误的注释比没有注释更糟糕。

2.3. 注释语言

• 项目内部统一：除非项目有特殊约定（例如，开源项目面向国际开发者），否则建议项目内部统一注释语言。
• 中文项目：对于主要面向中文开发者的项目，可以使用中文注释，但需注意专业术语的准确性。
• 国际化项目：对于可能需要国际协作的项目，推荐使用英文注释。

2.4. 注释不是代码的替代品

注释用于解释代码，而不是替代写出清晰、自解释的代码。应首先努力编写易于理解的代码，然后通过注释来解释那些代码本身难以表达的复杂逻辑或设计决策。

2.5. 避免多余的注释

不要为显而易见的代码添加注释。例如：

# 错误的示例 - 不必要的注释
i = i + 1 # 变量 i 自增 1

3. 注释类型

3.1. 块注释 (Block Comments)

• 用途：用于解释紧随其后的一个或多个代码段。通常用于解释复杂的逻辑、算法、重要的设计决策或代码节的总体功能。
• 格式：
  • 以单个 # 号和单个空格开始。
  • 每行注释都是一个独立的 # 注释。
  • 可以有多行。
  • 与它们描述的代码块具有相同的缩进级别。
• 示例：

  # 计算斐波那契数列的前 n 项
  # 使用迭代方法以提高效率
  results = []
  a, b = 0, 1
  while len(results) < n:
      results.append(a)
      a, b = b, a + b
  

3.2. 行内注释 (Inline Comments)

• 用途：用于解释单行代码中不明显的部分，如复杂的表达式、变量的特殊用途或某个技巧。
• 格式：
  • 在代码行的末尾，至少与代码隔开两个空格。
  • 以单个 # 号和单个空格开始。
• 注意事项：
  • 谨慎使用，避免过多行内注释使代码显得杂乱。
  • 不要解释显而易见的代码。
• 示例：

  x = x + 1  # 补偿偏移量
  MAX_RETRIES = 3  # 最大重试次数
  

3.3. 文档字符串 (Docstrings)

• 用途：为模块、类、函数、方法提供标准的说明文档。它们是 Python 语言的一个重要特性，可以被 help() 函数和各种文档生成工具（如 Sphinx）提取。
• 格式：
  • 使用三引号 """Docstring goes here.""" (推荐) 或 \'\'\'Docstring goes here.\'\'\'。
  • 文档字符串应在模块、类、函数或方法定义的下一行开始。
• 遵循 PEP 257 (Docstring Conventions) 规范：
  • 单行 Docstring：对于简单的函数/方法，可以使用单行文档字符串。结束的三引号应在同一行。

    def square(n):
        """Return the square of a number."""
        return n * n
    

  • 多行 Docstring：
    • 第一行是摘要行 (summary line)，简明扼要地概括对象的功能。摘要行应以大写字母开头，以句号结尾。
    • 摘要行之后是一个空行。
    • 接着是更详细的解释，可以包括参数说明、返回值说明、可能引发的异常等。
    • 结束的三引号应单独另起一行。
    • 推荐格式 (Numpy/Google 风格):

      def my_function(param1, param2):
          """一行总结函数的功能。
      
          更详细的描述可以放在这里，解释函数的行为、
          目的和任何重要的上下文。
      
          Args:
              param1 (int): 第一个参数的描述。
              param2 (str): 第二个参数的描述。
      
          Returns:
              bool: 返回值的描述。 True 表示成功, False 表示失败。
      
          Raises:
              AttributeError: 如果参数类型不正确。
              ValueError: 如果参数值无效。
          """
          if not isinstance(param1, int):
              raise AttributeError("param1 必须是整数。")
          if not param2:
              raise ValueError("param2 不能为空字符串。")
          # 函数逻辑
          return True