高效编写 Python 文档的方法

找到一种有效的方法来记录代码总是很重要的。挑战在于开发一种全面而简单的Python代码开发方法。让我们先看看Python注释，然后再看看文档字符串（docstring）。

Python 中的注释

与文档字符串相反，Python注释对运行时编译器不可见。它们被用作解释代码的注释。注释在Python中以 # 符号开头，如下所示：

# 这是一行注键，对运行时编译器不可见
print("Hello, world")

文档字符串 Docstring

记录代码的主要工具是称为docstring的多行注释块。Python语言的一个特点是DocStrings与对象相关联，可供检查。DocStrings的指南在Python增强提案（PEP）257中进行了描述。根据指南，其目的是为读者提供概述。它们应该在简洁和详细之间保持良好的平衡。DocStrings使用三重双引号字符串
格式或三重单引用格式：（""" 或 '''）。

以下是创建文档字符串时的一些一般准则：

• 文档字符串应放在函数或类定义之后。
• 文档字符串应该有一行摘要，后面是更多详细描述。
• 应有策略地使用空白来组织评论，但不应过度使用。您可以使用空行来组织代码，但不要过度使用它们。
  在接下来的部分中，让我们来看看docStrings的更详细的概念。

文档字符串类型

在开发代码时需要生成各种类型的文档，包括以下内容：

• 逐行注释；
• 功能或类级文件；
• 算法细节；

让我们逐一讨论它们。

逐行注释

文档字符串（docstring）的一个简单用途是使用它创建多行注释，如下所示：

"""
这是一个注释，
写在两行里。
这是对上面的补充。
"""
print("Hello,world")

函数和类级文档

文档字符串的一个强大用途是用于功能或类级文档。如果我们将文档字符串放在函数或类的定义之后，Python会将docstring与函数或类相关联。它被放置在该特定函数或类的__doc__属性中。我们可以在运行时通过使用__doc__属性或使用help函数打印出来，如下例所示：

def double(n):
	'''返回 n 的两倍的值'''
	return n * 2

print(double.__doc__) # 输出：返回 n 的两倍的值
help(double)

上面的 help(double) 输出内容很多，单独列出来：

Help on function double in module __main__:

double(n)
    返回 n 的两倍的值

当使用文档字符串来记录类时，推荐的结构如下：

• 摘要：通常为单行
• 第一个空白行
• 关于文档字符串的任何进一步解释
• 第二个空白行
  这里显示了在类级别使用文档字符串的示例：

class ComplexNumber:
    """
    这是一个关于复数的数学运算类。
    
    属性：
      real（int）：复数的实部。
      imag（int）：复数的虚部。
    """
    
    def __init__(self, real, imag):
        """
        ComplexNumber 类的构造函数。
        
        形参:
            real（int）：复数的实部。
            imag（int）：复数的虚部。
        """
        
    def add(self, num):
        """
        把两个复数加在一起的函数
        
        形参:
            num(ComplexNumber): 加数
        
        返回:
            ComplexNumber: 表示和的结果复数

        """
        
        re = self.real + num.real
        im = self.imag + num.imag
        
        return ComplexNumber(re, im1)

算法细节

Python项目越来越多地使用描述性或预测性分析和其他复杂的逻辑。所使用的算法的细节需要与所做的所有假设一起明确规定。如果一个算法被实现为一个函数，那么编写算法逻辑摘要的最佳位置是在函数签名之前。

<结束>