周三下午重构一个三年前写的工具库，发现函数参数改了但注释还是旧的。更崩溃的是，README里写的安装命令指向一个已经废弃的PyPI包名。这种文档与代码"各奔东西"的惨状，几乎每个开发者都经历过。
问题的根源在于混淆了两种文档的定位。文档字符串（docstring）和Markdown文档从来不是二选一的关系——它们服务不同的场景，面向不同的读者，解决不同的问题。
文档字符串是代码的"贴身说明书"。以Python为例，三引号包裹的注释块直接嵌在函数内部：
def calculate_total(items, tax_rate=0.08):
"""Calculate the total price including tax.
Args:
items: List of item prices.
tax_rate: Tax rate as decimal. Defaults to 0.08.
Returns:
Total price with tax applied.
"""
这种写法的核心价值在于"随行"。当其他开发者调用help(calculate_total)时，解释器直接提取这段注释；Sphinx、MkDocstrings等工具扫描源码时，也能自动构建API参考手册。Python社区形成了Google风格、NumPy风格等约定，JavaScript的JSDoc、Java的Javadoc同理——语法不同，逻辑一致。
Markdown文档则是项目的"门面担当"。README.md、教程指南、架构设计文档，这些.md文件与代码文件平级存放，但完全独立于代码逻辑。它们回答的是"为什么用这个库""怎么安装""典型场景怎么写"——这些问题需要代码示例、截图、架构图，显然不适合塞进函数定义里。
两种文档的关键差异在维护成本上暴露无遗。文档字符串跟着代码走，改函数时编辑器里的三引号就在旁边闪烁，很难彻底遗忘；Markdown文件是"编外人员"，版本迭代中极易与代码脱节。
但反过来，Markdown给了叙事空间：安装 troubleshooting、版本迁移指南、贡献者协议，这些内容没有docstring的容身之处。
实际操作的判断标准很简单：如果一段信息是"调用这个函数时需要知道的"，写进docstring；如果是"决定是否用这个库时需要知道的"，放进Markdown。API参考与项目指南，各司其职，缺一不可。
热门跟贴