PYTHON TUTORIAL
Python 注释怎么写？单行、多行与 docstring 用法详解
从“给代码加说明”，到真正理解注释、三引号与文档字符串的边界。
写在前面
注释编写得是否合理，往往会直接影响一段代码在后续阶段能不能被长期维护和稳定使用。好的注释并不是复述代码，而是帮助后来的人理解当初为什么这样设计。
这篇内容会讲清楚
01 单行注释应该解释什么
02 多行注释与三引号的区别
03 docstring 的用途与读取方式
01 / WHY COMMENTS
注释真正应该解释什么
代码负责表达“做什么”，注释重点说明“为什么”。
在刚开始开展 Python 学习的时候，我也曾经认为，注释的主要作用只不过是在代码旁边增加一些相对应的说明内容。后来随着自己编写的脚本越来越多，尤其是在处理文件读写、日志记录、接口请求以及自动化任务等相关场景的时候，我才逐渐意识到，注释编写得是否合理，往往会直接影响一段代码在后续阶段能不能被长期维护以及稳定使用。
KEY POINT
代码本身应该尽可能表达清楚正在做什么，注释则需要重点解释为什么要这样做。
02 / SINGLE-LINE COMMENT
单行注释：使用 # 说明处理原因
可以独立成行，也可以放在代码后面。
在实际开展代码编写的时候，我使用频率相对较高的注释方式就是 #。这种方式既可以写在某一行代码的上方，也可以放在代码后面，用来对当前代码的处理原因进行相对应的解释。
例如，为什么某一个接口的超时时间需要设置为 30 秒，为什么某一个变量不能直接写成固定数值，或者为什么一段业务逻辑必须先开展条件判断，然后才能继续执行后续操作，这些内容通常都值得被写进注释当中。
# 接口偶尔响应较慢，设置 30 秒避免过早中断
response = requests.get(url, timeout=30)
✓ 实用提示
优先记录超时时间、固定参数、条件顺序等设计原因，让维护者知道哪些地方不能随意修改。
不过，我现在已经很少编写那种只是把代码内容重新翻译一遍的注释。例如：
count = count + 1 # count 加 1
这类注释虽然在形式上对代码进行了说明，但是并没有提供新的信息。只要能够看懂基本语法，就可以直接判断这行代码的作用，因此这种注释所具有的信息价值往往比较低，还会在一定程度上增加阅读过程当中的干扰。
03 / MULTI-LINE COMMENT
多行注释：连续使用多行 #
Python 没有专门的多行注释符号。
多行注释也是很多 Python 新手比较容易产生误解的一个地方。Python 并没有专门提供类似其他语言那样的多行注释符号。如果我需要连续说明多行代码的处理逻辑，通常会在每一行说明内容前面都加上 #。
# 先检查配置文件是否存在
# 如果文件不存在，则创建默认配置
# 如果文件已经存在，则直接读取原有内容
这样的写法虽然看起来相对简单，但是表达方式比较清晰，同时也更加符合 Python 实际的语法规则。
三引号经常会被一些人用来暂时包住一段内容，因此看起来好像能够实现多行注释的效果。但是从 Python 本身的语法定义来看，三引号所创建的内容仍然属于字符串，而不是代码注释。
"""
这里本质上仍然是一个字符串，
并不是 Python 专门提供的多行注释。
"""
注意事项
如果这段字符串没有被赋值，也没有出现在函数、类或者模块开头，程序可能不会继续使用它，但这并不代表它在语法层面已经变成了注释。这个概念需要在学习阶段进行明确区分，否则后续理解文档字符串的时候，往往比较容易出现混乱。
04 / DOCSTRING
docstring：代码内部自带的说明文档
用于说明模块、函数或者类的用途、参数与返回结果。
当真正需要对模块、函数或者类的具体用途进行说明时，我通常会使用 docstring，也就是文档字符串。它一般被写在模块、函数或者类的开头位置，并且使用三引号进行包裹，用来描述这部分代码负责完成什么功能、接收哪些参数以及返回什么结果。
def read_log(file_path):
"""
读取指定路径下的日志文件。
参数：
file_path: 日志文件路径
返回：
日志文件的文本内容
"""
with open(file_path, "r", encoding="utf-8") as file:
return file.read()
与普通的 # 注释相比，docstring 不只是给阅读代码的人提供说明，它还能够通过 help() 函数或者 __doc__ 属性被程序读取。
help(read_log)
print(read_log.__doc__)
普通 # 注释
主要解释某一段具体代码为什么需要采用这样的处理方式。
VS
docstring 文档字符串
更像代码内部自带的一份说明文档，还能够被程序读取。
因此，docstring 更像是代码内部自带的一份说明文档，而普通注释则主要用来解释某一段具体代码为什么需要采用这样的处理方式。
∞ / SUMMARY
好的注释，是在减少后来的猜测
数量不是目标，信息价值才是。
现在我在编写注释的时候，主要遵循一个相对简单的原则：代码本身应该尽可能表达清楚正在做什么，而注释则需要重点解释为什么要这样做。
好的注释并不是数量越多就越好，而是要让后续负责维护代码的人减少猜测、减少踩坑，同时也减少因为不了解原有设计原因而产生的重复修改和返工情况。
对于刚开始学习 Python 的人来说，只要先把单行 # 注释、连续多行 # 以及 docstring 之间的边界理解清楚，并且尽量避免编写单纯翻译代码的低价值注释，整体代码质量就已经能够在一定程度上变得更加清晰和稳定。
SUMMARY
少写“代码做了什么”，多写“为什么必须这样做”。
如果你觉得今天这篇有收获
欢迎点赞、在看、转发三连，我们下篇见
