用 Python 编写注释的指南

什么是评论?

简而言之,注释是添加到源代码中的条目,以便更深入地了解代码按原样编写的原因背后的逻辑。 在 Python 中,每个注释前都需要“#”或井号。 此符号允许 Python 解释器或编译器忽略后续文本。

为什么需要评论?

在大型代码库中工作时,开发人员可能需要在数周或数月后重新参考评论中的信息,以确保他们了解代码的原始用途。 此信息对于原始想法的形式逻辑方面是必要的,并且是与其他开发人员合作进行广泛项目时的基本标准。

审查和/或跟进修改代码部分的开发人员通常严重依赖注释来识别和遵循原始开发人员的思维过程。 这样,后续开发人员可以添加、编辑或修改注解,以调整对代码更改时进一步更新的理解或推理。

注释约定

默认 Python 库要求代码行不超过 79 个字符。 这条规定对评论有所不同,评论为 72 个字符。 如果注释超出 72 个字符的文档字符串限制,则开发人员应添加以“#”符号开头的第二行。 通常需要不止一行来解释开发人员编写代码的方式或原因背后的原因。

添加评论时,应以完整的句子书写。 它还应该简洁地表达一个简单的想法,将解释的重点仅限于需要澄清的代码部分。

通常,开发人员应该将评论的第一个单词大写。 如果用作标识符,则首词应以小写字母开头。

Python 中的注释类型

单行块注释

单行块注释在行首使用“#”符号进行标记。 这意味着给定行上 # 符号之后的所有字符都是注释的一部分。 注释在行结束时结束。

#!/usr/bin/python3

# this is a single line comment describing the command below
command

内联评论

第二种单行块注释是内联注释。 内联注释与代码行存在于同一行。 通常,内联注释与 PEP 8 Python 样式指南中注明的语句至少用两个空格分隔。 使用单个空格是不受欢迎的,被认为是不好的形式。

#!/usr/bin/python3

for x in[1, 2, 3]:  # This is an inline comment 

多行注释

Python 没有像 Java 或 C 语言那样使用创建多行注释的特定功能。 但是,这并不意味着我们不能在 Python 中进行多行注释。 在我们的代码中创建多个注释行有两种主要方法。

块评论: 我们可以将几个单行注释串在一起来创建一个块注释。

#!/usr/bin/python3

# This is
# a multi-line
# comment.

for x in[1, 2, 3]:

我们还可以在注释的每一端使用分隔符来创建多行注释。 分隔符是三个双引号 (“””) 或三个单引号 (”’) 在评论的每一端串在一起。 如上所见 example 下面,开始分隔符之后的文本可以在同一行,但结束多行注释的分隔符应该单独在一行。

#!/usr/bin/python3

""" This is
a multi-line
comment as well!
"""

文档字符串

Python 还有一个内置概念,称为文档字符串或文档字符串。 文档字符串是缩进的字符串文字,位于函数下方并解释其作用。 这些文档字符串描述了一个函数、类、模块或方法。 该文本包含在模块下方的注释中。 它们是更合乎逻辑和更有用的评论版本

我们必须知道我们在代码中放置注释的位置。 如果后面有注释字符串:

  • 函数后太紧
  • 类的定义
  • 在模块的开头

它被读取为文档字符串; 这在 Python 中赋予了它完全不同的含义。 下面的代码提供了一个 example 一个文档字符串。 注意函数 result = a * b 下面的注释是如何缩进的? 这有助于更好地定义文档字符串。

#!/usr/bin/python3

def stuff(a, b): 
    result = a * b
    """
    Below, we define the sum
    of the result
    to use in function x
    """
    return result

在 Python 内置的 help() 系统或交互式帮助函数中使用 __doc__ 属性时,文档字符串还有助于关联和生成有关对象的文档。

有两种类型的文档字符串:

  • 单行:一个文档字符串位于一行。
  • 多行:文档字符串由类似于单行的摘要行组成,后跟一个空白行。 更详细的描述在空行之后。

对于文档字符串,始终打开并 close 使用“三重双引号”格式或“三重单引号”格式的注释。

这是一个 example 的单行文档字符串。

#!/usr/bin/python3

for x in[1, 2, 3]:
""" This is a general for loop syntax """ 

下面是一个 example 多行文档字符串。

#!/usr/bin/python3
def cars(GM, Ford, Chevy):
      """ This denotes the type and year of cars 
      GM 1992-2021
      Ford 1992-2021
      Chevy 1992-2021
      """ 

那么有什么区别呢?

那么,文档字符串和多行注释有什么区别呢?

文档字符串主要用于描述函数或提供上下文提示。 文档字符串缩进并位于函数下方,并解释函数的作用。 注释本身没有缩进,除了为试图理解代码逻辑的开发人员提供有用的信息外,不提供任何功能。 如果我们不将文档字符串分配给变量,它将充当注释。

评论的最佳实践

  1. 确保评论尽可能简短和具有描述性,而不会丢失上下文。
  2. 总是使用注释来描述代码的逻辑,而不是它是如何工作的。
  3. 限制多余的评论。 不要对类似名称的函数一遍又一遍地使用相同的注释。 对函数使用更好的命名约定可以解决这个问题。

结论

注释是每个 Python 脚本或程序不可或缺的一部分。 它们描述了代码块的功能、目的或预期输出。 几乎可以在任何情况下使用多种类型的注释,从而提高代码块的清晰度和细节。 此外,文档字符串可以用作注释,也可以在 Python 交互式帮助系统中生成有关对象的文档。 注释是任何代码库不可或缺的一部分,应根据需要经常使用。 在解释代码存在的逻辑及其存在背后的原因时,它们特别有用。 这样想吧。 如果您编写了一个代码部分并在六个月后回来并且不明白它的作用或使用它的原因,请为它写一个注释。