__doc__ 属性为空时，IDE悬停、help()、Sphinx全失效；类docstring必须顶格写在class语句正下方第一行，用三重双引号包裹，否则MyClass.__doc__为None，导致工具链失去上下文。
__doc__ 属性为空时，IDE 悬停、help()、Sphinx 文档生成全失效——这不是“可有可无”的注释，而是 Python 运行时直接绑定的元数据。
类 docstring 必须顶格写在 class 语句正下方第一行
位置错一点，MyClass.__doc__ 就是 None。常见错误包括：
- 在
class行后加空行再写三引号字符串 - 把 docstring 写成变量赋值：
doc = """...""" - 用三重单引号
'''—— PEP 257 明确要求用三重双引号"""
正确写法只有一种：
class DataProcessor:
"""对原始数据进行清洗、归一化与缓存的工具类。
支持 CSV/JSON 输入，输出为 Pandas DataFrame。
"""
def __init__(self, cache_dir: str):
...
不写类 docstring，help() 和 IDE 提示就只剩个空框
当你在终端输入 help(DataProcessor)，或在 VS Code / PyCharm 中悬停类名，看到的全是默认模板信息（比如 class DataProcessor(builtins.object)），没有任何业务说明。
这是因为解释器只认 __doc__ 属性，而该属性只从合法 docstring 自动填充。没有它，工具链就失去上下文。
立即学习“Python免费学习笔记（深入）”；
尤其在团队协作中，别人第一次 import 你的类时，靠的不是翻源码，而是 help() 或文档站点——这两者都依赖这个字符串。
类 docstring 要覆盖“谁用、怎么用、边界在哪”三个真实问题
光写“这是一个数据处理器”没用。实际开发中，调用方真正需要知道的是：
-
__init__的参数是否必须？cache_dir能否为None？ - 有没有隐式副作用？比如自动创建目录、读取网络配置？
- 线程安全吗？能否被多个实例并发调用？
- 抛出哪些异常？
OSError还是自定义的DataLoadError？
这些内容写进 docstring 第三段（空行之后），比散落在注释里或 Wiki 页面上更可靠——它和代码永远在一起，不会过期。
模块级和类级 docstring 不是重复劳动，而是不同粒度的契约
模块 docstring 回答“这个文件整体干啥”，类 docstring 回答“这个类型具体承诺什么”。比如：
- 模块
io_utils.py的 docstring 可能说：“提供统一的数据加载与序列化接口”； - 其中的
JsonLoader类 docstring 就得明确：“仅支持 UTF-8 编码 JSON；不处理循环引用；超时默认 30 秒”。
漏掉类 docstring，等于把关键契约藏在实现细节里——等别人踩了编码错误或超时陷阱才去翻源码，代价远高于开头多写十行字。
