Python 如何写好注释与文档字符串

---

一、注释

注释是每个计算机语言的重要组成部分，用于在源代码中解释代码的功用，可以增强程序的可读性，可维护性，或者用于在源代码中处理不需运行的代码段，来调试程序的功能执行。想必很多人都了解 Python 的注释，Python 的注释分单行注释和多行注释，对于多行注释而言会用到一个Python独一无二很厉害的文档字符串，这也是下面内容要提到的，在当前部分将会稍微讲讲单行注释。

单行注释没什么特别的，Python 语言下只需要在注释内容前加一个 # 号既是一个注释

# 这是一个注释

对于当行注释上来讲更多体现在书写习惯上，单行注释应该放在 代码行尾 还是 代码上方。

• 代码行尾注释

  对于代码量比较少或是声明变量时等操作时，可以考虑将注释写在行尾，这样出来的代码比较简洁、简短，想要进一步美观的话可以将行尾注释对齐。
  拿 Python 算法之 斐波拉契数列2.0 文章下求素数的代码示例：

  def fib(n: int) -> int:
      if n == 0:
          return 0
      prev, curr = 0, 1
      f_arr = [prev, curr]                # 新建数组，并且将初始值放入
      for _ in range(n-1):
          prev, curr = curr, prev+curr    # 同时进行赋值
          f_arr.append(curr)              # 添加新的当前值
      return curr                         # 返回当前值
  

• 代码上方注释

  在代码量比较大的时候或是某行代码过长时可以考虑将注释写在代码上方，这样做的好处在于可以与上一行代码隔离开能够清晰一些，且方便直接。这也是大多数程序员的做法。
  简单拿 Python 算法题之 俄罗斯套娃信封 文章下动态规划算法代码示例：

  def max_envelopes(envelopes: list) -> int:
  if not envelopes:
      return 0
  length = len(envelopes)
  # 排列规则：对宽度 w 进行升序排序，如果 w 相同时，则按高度 h 降序排序
  # 全升序排列
  envelopes.sort(key=lambda x: (x[0], x[1]))			
  dp = [1] * length
  # 小优化，从1开始循环，dp[0]为最小情况1,即只有自己一个的最长递增子序列
  for i in range(1, length):
      for k in range(i):
          if envelopes[i][1] > envelopes[k][1] and envelopes[i][0] > envelopes[k][0]:
              dp[i] = max(dp[i], dp[k] + 1)
  return max(dp)
  

  刚开始写代码那会，我所编写的代码量并不大，我更加习惯讲注释写在代码行尾。
  但随着时间推移写的代码量越来越大，往往有着那么几行很长的代码，如果写在行尾一是会影响阅读体验，因为还要往后翻且不美观，二是若将注释对齐难度高且浪费时间，对于代码量比较多时我习惯将注释放在代码上方，但对于代码量比较少时我偏向于将注释写在行尾。

其实也就一句话：注释只是为了增加代码的可阅读性，怎么样写注释能够使代码美观、提高阅读体验就怎么来。

---

二、文档字符串

文档字符串（DocString）注重于解释怎么使用模组、类、方法与函数，对于每个模组、类、方法与函数都应该编写 DocString 文档，并且要与实现代码保持同步。注释（Comment）注重解释代码实现的细节。

Python这门语言内建了相关的机制，支持给代码块编写文档，而且与其他一些编程语言不同，Python允许在程序运行的时候，直接访问这些文档。

• 文档字符串的书写惯例是首位都使用三重引号，也就是多行注释，在其中书写内容。

  """文档字符串
  
  内容
  """
  

• Python 的 DocString 可以关联到函数、类与模块上面，系统在编译并运行 Python 程序的过程中，会把确定这种关联的关系也当成工作的一部分。

• Python 允许程序通过 __doc__ 属性来访问 DocString，对函数、类与模块都适用。

  >>>import string
  
  >>># 模块文档字符串
  >>>print(string.__doc__)
  A collection of string constants.
  Public module variables:
  whitespace -- a string containing all ASCII whitespace
  ascii_lowercase -- a string containing all ASCII lowercase letters
  ascii_uppercase -- a string containing all ASCII uppercase letters
  ascii_letters -- a string containing all ASCII letters
  digits -- a string containing all ASCII decimal digits
  hexdigits -- a string containing all ASCII hexadecimal digits
  octdigits -- a string containing all ASCII octal digits
  punctuation -- a string containing all ASCII punctuation characters
  printable -- a string containing all ASCII characters considered printable
  
  >>># 类别文档字符串
  >>>print(string.Template.__doc__)
  A string class for supporting $-substitutions.
  
  >>># 函数文档字符串
  >>>print(string.capwords.__doc__)
  capwords(s [,sep]) -> string
      Split the argument into words using split, capitalize each
      word using capitalize, and join the capitalized words using
      join.  If the optional second argument sep is absent or None,
      runs of whitespace characters are replaced by a single space
      and leading and trailing whitespace are removed, otherwise
      sep is used to split and join the words.
  

• 开发者能够在程序中访问文档信息，这会让交互式开发工作变得更加轻松。用内置函数 help 能够查看某个函数、类及模块响应的文档，对很多编辑器、高级工具都可以很方便的查阅文档。这些辅助能够让我们很愉快的编写代码片段、测试API。

• 扩展：在命令行界面中，利用标准库 pydoc 模块可以在本机上启动web服务器，这个服务器能够提供当前 Python 解释器所能访问到的全部文档，包括自己编写的模块

  $ python -m pydoc -p 8080
  Server ready at http://localhost:8080/
  Server commands: [b]rowser, [q]uit
  # 输入b打开默认浏览器，输入q退出服务器
  

  

文档字符串的写法有很多种，下面挑比较常用的两种进行讲解

---

三、reStructuredText 格式写法

reStructuredText（RST、ReST或reST）是一种用于文本数据的文件格式，也是一种轻量级标记语言，主要用于 Python 编程语言社区的技术文档，有着强大的扩展性

可以将 reStructuredText 理解成 Markdown 文档，写法与 Markdown 类似，都是简单的标记语言。
reStructuredText 也是 文档生成器 Sphinx 默认使用的纯文本标记语言，使用 reStructuredText 语法配合 Sphinx和Read the Docs 能够生成美观的文档存放在网站中。完整的reStructuredText语法示例，可以查看 Sphinx - reStructuredText。

• 为文档处理软件（如Docutils）可以处理解析 reStructuredText。
• 对于Python 源代码的注释，阅读体验上会显得美观整洁，程序员易于编写。

编写Python 文档字符串中，一般只用到 reStructuredText 字段列表 和 文字块 语法。文字块语法一般在编写复杂文本内容时用上，比如贴入代码片段。

def func(name, job="程序员"):
    """拼接姓名与职业函数

    这是一个简单的函数，用于示例reStructuredText文档字符串编写格式
    :param name: 姓名（string）
    :param job: 工作类型，默认值为'程序员'（string）
    :return: 字符串拼接结果（string）

    使用示例::

        此处是'文字块'内容，
        而对于上面格式如 :fieldname: Field content而言的内容则是 '字段列表'

    """
    return f"姓名：{
      name}, 职业：{
      job}"

---

四、PEP 257 文档字符串规范

Python 对于文档字符串其实有着自己的一套规范 PEP 257，就与编程规范 PEP8 一样，如果想将 Python 文档字符串写好，那就需要遵循一些与 文档字符串 有关的约定。

1)、为模块编写文档

每个模块都要有顶级的 文档字符串，即写在源文件开头的字符串文档。

• 第一行应是一个单句，用简单明了的语句描述本模块的用途。
• 接下来应该另起一段，讲述使用这个模块时所需要知道的一些事项。
• 模块里比较重要的类与函数，都应该在文档字符串中予以强调，这样的话，查看这份文档的用户就能够从这些内容中熟悉模块。

模块文档字符串示例

# -*- coding: utf-8 -*-
# link.py
"""操作Selenium对浏览器行为主源代码模块

本模块用于对浏览器的行为控制，对浏览器驱动实例化，包括但不限于重启浏览器，页面加载策略配置,
浏览器启动参数设置，切换标签页等。
提供页面元素捕获以及对页面元素动作链行为API接口。

Available functions:
- ElementCapture: 页面元素捕获类
- Action: 页面元素动作链控制类
- WebDriver: 浏览器驱动类, 对浏览器的行为都由该类控制
"""

2)、为类编写文档

每个类都应该有类级别的文档字符串，这种文档的写法，与模块级别的文档字符串差不多。

• 第一行应是一个单句，用简单明了的语句描述整个类的用途。
• 类中比较重要的 public（公共）属性与方法，同样应该在类级别的文档字符串里面加以强调。
• 如果需要编写子类，应说明子类应该怎样与受保护的属性以及超类中的方法相交互。

类文档字符串示例

将比较重要的方法和属性强调即可，不需要将全部列出来。为了便于阅读和理解，这里单独写上了 Public functions 声明，其实可以将重要的方法写入到 Public attributes 里，方法也可以被称为整个类的属性。

"""浏览器驱动类

控制浏览器的行为动作,实例为浏览器驱动对象。
本类继承ElementCapture类与Action类，在本类中能够直接使用这页面捕获以及动作链的接口。
继承此类时，子类如需要重写'start_browser'方法，确保该方法能够正确返回浏览器对象，类全局属性
'browser'在实例化时，依靠该方法返回的浏览器对象，同时若需要使用到浏览器启动参数配置话还需重写
'init_startup_param'方法。对于加载策略'no_wait_page'方法若不是业务需要将没必要重写。

Public attributes:
    - url: 浏览器发起请求的目标网址（string）
    - browser_means: 使用的浏览器类型（string）
    - headless: 是否开启无头浏览器模式（True or False）
    - startup_param: 浏览器启动参数配置（dict）
    - explicit_sleep: 显示等待时长（float）

Public functions:
    - init_startup_param: 浏览器启动参数初始化方法（Options obj）
    - no_wait_page: 配置页面加载策略方法（Options obj）
    - start_browser: 启动浏览器方法（WebDriver obj）
"""

3)、为函数和方法编写文档

每个 public（全局变量）函数与方法都应该有文档字符串，这也是文档字符串用的最多的地方，在我很多文章中对这些函数、方法写了文档字符串，美观易读，对熟悉这些函数、方法有着很大作用。

• 第一行应是一个单句，描述这个函数方法是干什么用的。
• 用每一行的形式分别描述函数方法的参数与返回值。
• 如果函数和方法没有参数，且返回值是应该比较简单的值，那么一句话描述整个函数和方法是最好的。
• 如果该函数和方法会抛出异常，那么调用者在使用这个函数接口时，需要处理那些异常，对其进行解释。
• 对函数和方法在正常使用的过程中，不会抛出异常，那么就无须专门指出这一点。
• 如果函数和方法没有返回值，那么最好把描述返回值那段完全省去，而不要专门写出返回 None。
• 如果参数有默认值，那么文档内容里应该提到这些默认值。

类文档字符串示例

"""启动浏览器方法

依据使用需求传递浏览器启动参数、页面加载策略实例化浏览器对象，现支持实例化Edge、Chrome浏览器对象
Args:
    browser_means: 启动浏览器类型
    inplace: 是否在对象属性基础上内部赋值，将不再有返回值

Returns:
    若inplace为False时则返回启动的浏览器对象，反之返回为空

Raises:
    BrowerTypeException: 若指定的浏览器类型不存在，则会抛出此异常
"""

4)、声明样式

对于声明样式其实没有特别严格的限制，只要格式规范即可，可以根据自己的使用习惯或则团队的要求来制定。

Google 关于 Python 代码风格规范中对文档字符串也有进行解释，参考了 PEP 257 而制定。

• Attributes：
  可以直接将 Public attributes 简写为 Attributes，将比较重要的方法和属性强调即可。

• Args：
  列出每个参数的名字, 并在名字后使用一个冒号和一个空格, 分隔对该参数的描述.如果描述
  太长超过了单行80字符，使用2或者4个空格的悬挂缩进(与文件其他部分保持一致). 描述应该
  包括所需的类型和含义。如果一个函数接受 *foo (可变长度参数列表)或者 **bar (任意关键字参数), 应该详细列出 *foo 和 **bar。

• Returns: (或者 Yields: 用于生成器)：
  描述返回值的类型和语义，如果函数返回 None，这一部分可以省略。

• Raises:
  列出与接口有关的所有异常.

对于函数和方法，Google示例

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
	"""Fetches rows from a Bigtable.
	
	Retrieves rows pertaining to the given keys from the Table instance
	represented by big_table. Silly things may happen if
	other_silly_variable is not None.
	
	Args:
		big_table: An open Bigtable Table instance.
		keys: A sequence of strings representing the key of each table row
		to fetch.
		other_silly_variable: Another optional variable, that has a much
		longer name than the other args, and which does nothing.
	
	Returns:
		A dict mapping keys to the corresponding table row data
		fetched. Each row is represented as a tuple of strings. For
		example:
		{'Serak': ('Rigel VII', 'Preparer'),
		'Zim': ('Irk', 'Invader'),
		'Lrrr': ('Omicron Persei 8', 'Emperor')}
		If a key from the keys argument is missing from the dictionary,
		then that row was not found in the table.
		
	Raises:
		IOError: An error occurred accessing the bigtable.Table object.
	"""
	pass

---

五、使用类型注释来简化Dostring

使用类型注释就不用专门在 文档字符串 里说明各参数，原本写在 文档字符串 里面的某些含义，现在可以直接通过类型注解体现出来，简化了对文档字符串的编写。
编写函数时，在位置参数右侧书写一个冒号，再在冒号右侧标出其类型，如 def func(param: str): ，其意思为 param 参数的数据类型为 str。在声明函数时，函数右侧用 -> 符能够说明函数会返回什么样的数据类型，如 def func() -> list: 能够说明 func 函数将会返回一份列表。

编写斐波那契数列数组 函数示例

def fib_arr(max_: int) -> list:
    """生成斐波那契数列数组函数

    Args:
        max_: 数值范围最大值

    Returns:
        指定范围的斐波那契数列数组
    """
    # 如果范围的最大值小于1则直接返回空列表
    if max_ < 1:
        return []
    prev, curr = 0, 1
    f_arr = [prev, curr]                # 新建数组，并且将初始值放入
    while prev+curr <= max_:
        prev, curr = curr, prev+curr    # 同时进行赋值
        f_arr.append(curr)              # 添加新的当前值
    return f_arr                        # 返回当前值

---

六、扩展：Pycharm对文档字符串的支持

Pycharm 已经帮我们准备好了对文档字符串的应用，在设置中能够调试文档字符串的格式

Settings>Tools>Python Integrated Tools>Docstrings

在函数和方法中输入三重引号，并在三重引号中间回车，会自动生成文档字符串格式

Google文档字符串自动生成格式

reStructuredText 文档字符串自动生成格式

---

参考资料

• 书籍：
  • Effective 系列丛书 《Effective Python》
    这算是我最喜欢的 Python 书之一，非常推荐给大家
• 官方手册：
  • reStructuredText 官方英文
  • reStructuredText 中文文档
  • Sphinx - reStructuredText
• 维基百科中文版：
  • reStructuredText
  • 注释 (程序设计)

---

文件下载

• Python语言规范 — Google 开源项目风格指南.pdf
• Python风格规范 — Google 开源项目风格指南.pdf

---

相关博客

• Python 编程规范指南详解 上
• Python 你可能不知道的 Boolean 表达式b(￣▽￣)d