接口注释

Python 接口注释有好几种流行的风格，比如 Sphinx 文档风格、Google 风格等，其中 Sphinx 文档风格目前应用得最为广泛。

下面的 Person 类的接口注释就属于 Sphinx 文档风格：

1
class Person:
2
    """人
3

4
    :param name: 姓名
5
    :param age: 年龄
6
    :param favorite_color: 最喜欢的颜色
7
    """
8

9
    def __init__(self, name, age, favorite_color):
10
        self.name = name
11
        self.age = age
12
        self.favorite_color = favorite_color

指引式注释

指引性注释。这种注释并不直接复述代码，而是简明扼要地概括代码功能，起到“代码导读”的作用。

1
# 初始化访问服务的client对象
2
token = token_service.get_token()
3
service_client = ServiceClient(token=token)
4
service_client.ready()
5
# 调用服务获取数据，然后进行过滤
6
data = service_client.fetch_full_data()
7
for item in data:
8
    if item.value > SOME_VALUE:
9
        ...

指引性注释的主要作用是降低代码的认知成本，让我们能更容易理解代码的意图。