1.指引性注释
#初始化访问服务的client对象
token = token_service.get_token()
service_client = ServiceClient(token=token)
service_client.ready()
# 调用服务获取数据,然后进行过滤
data = service_client.fetch_full_data()
for item in data:
if item.value > SOME_VALUE:
...
2.弄错接口注释的受众
未优化前:
def magic_bubble_sort(numbers):
j = len(numbers) - 1
while j > 0:
for i in range(j):
if numbers[i] % 2 == 0 and numbers[i + 1] % 2 == 1:
numbers[i], numbers[i + 1] = numbers[i + 1], numbers[i]
continue
elif (numbers[i + 1] % 2 == numbers[i] % 2) and numbers[i] > numbers[i + 1]:
numbers[i], numbers[i + 1] = numbers[i + 1], numbers[i]
continue
j -= 1
return numbers
优化后:
def magic_bubble_sort(numbers: List[int]):
"""有魔力的冒泡排序算法,默认所有的偶数都比奇数大
:param numbers: 需要排序的列表,函数会直接修改原始列表
"""
stop_position = len(numbers) - 1
while stop_position > 0:
for i in range(stop_position):
current, next_ = numbers[i], numbers[i + 1] ➊
current_is_even, next_is_even = current % 2 == 0, next_ % 2 == 0
should_swap = False
# 交换位置的两个条件:
# - 前面是偶数,后面是奇数
# - 前面和后面同为奇数或者偶数,但是前面比后面大
if current_is_even and not next_is_even:
should_swap = True
elif current_is_even == next_is_even and current > next_:
should_swap = True
if should_swap:
numbers[i], numbers[i + 1] = numbers[i + 1], numbers[i]
stop_position -= 1
return numbers
(1)变量名变成了可读的、有意义的名字,比如在旧代码里,“停止位”是无意义的j,新代码里变成了stop_position。
(2)增加了有意义的临时变量,比如current/next_代表前一个/后一个元素、{}_is_even代表元素是否为偶数、should_swap代表是否应该交换元素。
(3)多了一点儿恰到好处的指引性注释,比如说明交换元素顺序的详细条件。