今天讲三件事：注释到底分哪几类、它在调试时有什么妙用、以及判断注释好不好的三个标准。

一、注释分三类，别只会写一个井号

（1）行内注释：解释"为什么这么做"

注释：以井号开头、解释器不执行的说明文字，用来解释代码。

这条定义里藏着两个信息：它不参与运行，它的职责是"解释"。

真正有价值的注释，回答的是代码看不出来的那部分。举个对照：同样是处理订单金额，坏注释写"把金额乘以折扣"，好注释写"折扣按平台规则取整到分，避免对账差额"。前者在复述代码，后者交代了代码里看不出来的业务约束——哪天规则改了，你一眼就知道该动哪里。

一句话总结：写原因，不写动作。

（2）块注释：给一整段逻辑加个路牌

行内注释：写在代码行尾、紧邻该行语句的简短说明。它适合解释某一行。

而当你有一整段逻辑需要交代背景时，就该用块注释：在段落开头单独起几行，把这段要解决的问题、采用的思路、以及踩过的坑讲清楚。

（3）文档字符串：给函数写一份说明书

这是最被低估的一类，很多入门教程一句带过，实际工作中却天天要用。

文档字符串：写在函数或模块开头的字符串，用于说明用途并支持自动生成文档。

它和前两类最大的区别在于：注释是给人看的，文档字符串既能给人看，也能被工具读取。你在编辑器里调用一个函数时，自动弹出的那行提示，多半就来自它。

唯一要注意的是保持更新——过期的文档字符串，比没有更糟。

二、调试时的隐藏用法：注释是最朴素的排错工具

（1）临时禁用：最快的问题定位法

注释还有个很实用的身份——测试时用来阻止代码执行。

程序报错却找不到源头时，最直接的办法就是把可疑的那几行注释掉，看看错误是不是消失了。消失了，说明找对了；还在，说明不在这儿。

具体怎么用：一个脚本跑完报了个看不懂的错，先把它最后调用的那一句注释掉。错误消失了，问题就在那句；错误还在，说明前面早就出事了。比起从头到尾通读一遍，省事太多。这种办法看着笨，实际效率很高。它不需要配置任何工具，随手就能做，尤其在排查刚写完的脚本时特别顺手。

（2）二分法：注释掉一半，快速圈定范围

当代码很长、无从下手时，我会用二分法：先注释掉后半部分，看前半部分是否正常运行。正常，问题就在后半段；不正常，问题在前半段。然后对有问题的那一半再来一次。

几百行的脚本，五六轮就能把问题锁到具体几行。我刚工作那会儿不懂这个，一行行地看，一个下午就这么过去了。后来发现，这个思路不只适用于代码，排查配置问题、排查数据异常都一样好用——只要能切成两半，范围就能快速收敛。

（3）进阶优化方案：别把代码留在注释里

说完用法，得提一个几乎人人都有过的坏习惯：调试完只把代码注释掉，而不是删掉。

理由听起来很合理——"万一以后还要用呢"。实际结果是，三个月后没人记得那段注释是什么、为什么留着、还能不能用。注释里的代码没有测试覆盖，随时可能和现在的逻辑不兼容，留着就是定时炸弹。

真正稳妥的做法，是用版本控制系统保存历史。版本控制：记录并管理代码每次变更的系统，可随时回退到历史版本。需要旧代码时去历史里翻，比在注释里考古靠谱得多。删掉，往往比留着安全。

三、判断注释好不好的三个标准

（1）改代码的时候，记得改注释

注释最大的敌人不是写得少，是它过期了。

我吃过这个亏。早年写过一段采集脚本，注释里明明白白写着"此处需要延时，防止被限制"。后来接口换了，延时早就不需要，但注释还在。新同事照着注释改了一遍，白白多加了等待时间，还以为自己在遵守规矩。

错的代码会报错，错的注释不会——它只会安安静静地把下一个人带沟里。所以我的规矩是：改逻辑的那一次提交里，必须同时处理相关注释。

（2）需要注释才能懂，先想想是不是该重构

重构：在不改变外部行为的前提下，优化代码内部结构的改动。

有些注释存在的唯一原因，是这段代码本身就写得绕。与其花三行解释它在干什么，不如把它改写到不需要解释。

常用的手法有三种：把很长的表达式先存进命名清楚的变量，把一段逻辑抽成独立函数，把来历不明的数字换成有意义的常量。这三板斧下去，多数注释就自然失去了存在的必要。

判断标准也很简单：写注释时如果觉得"不解释一下真看不懂"，先试试换个写法；改完还觉得需要，再动笔。

（3）约定几个标记，团队沟通会顺很多

有些注释是留给未来的任务清单。常见的做法是约定几个统一标记：待办事项、已知缺陷、需要重点检查的地方。

关键不在用哪个词，而在全队统一。编辑器大多能高亮这些标记，还能把它们汇总成列表。定期清一遍这个列表，比翻聊天记录找需求靠谱。

别小看这一点。小团队里，这往往就是最轻量、也最不容易丢的协作方式。

更多相关技术内容咨询欢迎前往并持续关注好学星城论坛了解详情。

想高效系统的学习Python编程语言，推荐大家关注一个微信公众号：Python编程学习圈。每天分享行业资讯、技术干货供大家阅读，关注即可免费领取整套Python入门到进阶的学习资料以及教程，感兴趣的小伙伴赶紧行动起来吧。