写Python注释还有规范？按这个来，同事都夸你代码像文档
刚工作那会儿，我特别讨厌写注释。觉得代码自己能看懂就行，注释是浪费时间。
有一次接手一个老项目，打开文件直接蒙了。一个函数三百行，没有一句注释。变量名字是a,b,c。当时真想骂人。后来自己返工查自己三个月前的代码，同样认不出写了什么。
从那以后，我开始认真研究注释怎么写。不是那种“这里加了一个数”的废话，是真正能帮到人的注释。
核心就一条：注释要说“为什么”，不要说“是什么”。
代码本身就能表达“是什么”。变量赋值，函数调用，逻辑判断，这些都是代码在说的内容。注释再多说一遍就是噪音。
比如这样写的注释就很蠢：
把a赋值给b
b = a
谁看不出来？真正需要注释的是那些隐形的上下文。
函数注释要写清楚输入输出，最好带类型和例子。
很多人写函数注释只写一行，说“这个函数处理数据”。等于没写。应该这样：
def parse_user_info(raw_data):
'''解析用户信息
Args:
raw_data: dict, 来自接口的原始数据, 结构见文档X
Returns:
dict: 包含name, age, email三个字段
Raises:
ValueError: 缺少必要字段时抛出
'''
别人看到这个注释，立刻知道怎么调，返回什么，出错怎么办。不用再去看文档，不用翻代码。
代码块注释要讲业务目的。
业务逻辑是最容易看不懂的。比如有一段排序代码，为什么用冒泡排序不用快速排序，可能是数据量很小。这时候注释要写“接口返回数据量小于100条，冒泡排序够用且稳定”。
再比如一段复杂的条件判断，为什么是这几个条件。可能是因为业务规则里要求同时满足ABC三种情况。直接写“根据业务规则A和B和C的复合条件过滤”，比写一大堆if判断的推理过程有用得多。
难懂的算法逻辑要单独加行内注释。
有时候算法本身就很绕。比如递归处理树形结构，或者用位运算做状态判断。这种地方不写注释，别人看三遍也可能看不懂。可以在关键逻辑前加一行，简单说“这一步是为了避免重复计算”或者“利用异或运算判断奇偶差异”。
有个小技巧。变量名字起得好，注释能少一半。
把temp换成user_input，把data换成order_list。代码自己就在说话。注释就用来补代码说不清的部分。
还有一个容易被忽视的，TODO注释要写明责任人。
很多人写TODO就写“后面要优化”。下次谁看到这句话都犯愁，不知道谁写的，不知道啥时候改。正确的写法是“TODO(张三): 提升查询性能, 计划用缓存替代”,这样别人就知道该找谁问，也知道问题背景。
我见过最好的注释风格，是一个同事写的。他的代码里，每个文件开头有一段目录注释，列出文件里有哪些类哪些函数，大概什么功能。新同事看代码，先看这段目录，对整个文件心里就有数了。这个习惯我后来也学了，确实好用。
还有个规矩，注释必须和代码同步更新。
代码改了，注释不改，比没写注释还坑。别人看着旧的注释理解新代码，肯定出问题。所以每次改代码，顺手看一眼相关注释要不要改。养成习惯就不觉得麻烦。
最后说个实在的。注释写得好不好，有个最简单的检验标准。把你所有的注释摘出来，如果拼在一起能讲清楚整个业务逻辑，注释就合格了。
同事夸你代码像文档，不是夸你注释多，是夸你的注释精准有用。少即是多，重点说清楚“为什么这样写”，比堆砌一大堆“做了什么”强得多。
写注释不花多少时间，省的是后面翻代码骂娘的时间。你试试看，坚持半个月，同事对你的评价绝对不一样。
