5.2 函数书写规范

5.2.1 文档字符串

良好的代码书写规范不仅便于他人阅读，更是一个开发人员应有的素养。由于函数往往用于实现一系列复杂的逻辑运算，所以在编写函数时更应该注意代码规范，使函数调用者能够准确理解函数的使用方法，图5-1是Python内置的print函数的注释。

图5-1

从截图中可以知道，print函数的作用是将一些值打印到一个流对象或者系统的标准输出设备。同时还提供了几个可选参数进行复杂的打印操作。

自定义的函数也应提供合适的函数注释，帮助使用者理解函数。

在Python中使用文档字符串（DocString）可以提供对函数功能的说明，文档字符串存储在__doc__中。文档字符串必须出现在模块、方法、类或者函数内部的第一行。Python官方推荐所有的模块以及模块内部的类与方法都应该有文档字符串，另外类的所有公共方法如构造函数（__init__）也应该提供文档字符串。

Python推荐使用三个双引号将文档字符串括起来，如"""Add two numbers."""。如果在文档字符串中出现了反斜杠（/），则需要在文档字符串前添加小写字母r，如r"""It\'s a function to get the summary of two numbers."""。如果文档字符串中出现了unicode字符，则需要在字符串前添加一个小写字母u，例如：u"""计算两数之和。"""。

单行文档字符串的书写有以下注意事项：

□ 即使文档只有一行，也要使用三引号将字符串括起来。

□ 如果文档只有一行，那么三引号开头与结尾也要在一行。

□ 在文档字符串中不能出现任何空白行。

□ 文档字符串用来描述方法或函数的作用，而不能有其他描述性的文字。

□ 文档字符串中不要重复出现函数的签名，如"""function(a,b)->list"""。

多行文档字符串的书写有以下注意事项：

□ 第一行类似于单行文档字符串，用于表达总结性的信息，其后紧跟一个空行，最后是更详细的描述性信息。

□ 总结性的信息必须紧跟在开始三引号之后。

□ 详细的描述信息的缩进应该与三引号一致。

一个包含多行文档字符串的示例如下：

此时在Visual Studio Code中调用上面complex方法时也会给出提示信息，如图5-2所示。

图5-2

5.2.2 函数注释

除了文档字符串外，在Python 3中还提供了一个新功能：函数注释。函数注释完全是一个可选的功能，它以字典的形式存储在__annotations__中，不会对函数本身造成任何影响。

函数注释的使用方法为：

    def 函数名(参数名："参数注释"="默认值", …) -> "函数返回值注释":
        函数体

例：修改add方法，添加相应的函数注释：

    def add(x:"Number 1"=0, y:"Number 2"=0) -> int:
        """Add two numbers."""
    return x + y

调用add方法：

        >>> print(add.__annotations__)
    >>> sum = add()
    >>> print(sum)

输出：

    {'x': 'Number 1', 'y': 'Number 2', 'return': <class 'int'>}
    0

由此可见，函数参数、返回值的说明信息都被保存在属性__annotations__中，方便用户了解并使用函数。