接口注释

2023-02-01

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
...

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