代码示例跑不通，比没有示例还糟

开发者对代码示例的信任度，比对文字描述高得多

一条让我心跳加速的社区帖子

"照着你们的文档复制代码，直接报错。你们自己试过吗？"

我去查了一下那个代码示例。问题出在三处：

问题1 示例里的API端点从v1改成了v2，但示例没更新

问题2 示例用了 <your-api-key> 占位符，但没说去哪里获取

问题3 示例依赖的SDK版本跟文档标注的不一致，文档写的v3.2，示例里还是v2.x语法

没有示例，开发者会自己试；跑不通的示例，开发者会认为你的API有问题。

坑一：占位符没说明

❌ <your-api-key>

✅ <your-api-key>（在控制台 → 账户设置 → API密钥页面获取，创建后仅显示一次，请妥善保存）

我见过最离谱的示例，里面有三个占位符 <host>、<port>、<token>，没有一个说明怎么填，开发者在工单里问"host填什么"，回复是"请参考部署文档"——部署文档里也没写。

坑二：依赖没标注

一个Python示例用了 requests 库，但没说需要先安装。还有示例用了Python 3.8+的f-string语法，但没标注版本要求，用3.6的人跑不了，还以为是API的问题。

正确做法：在代码示例前标注"需要Python 3.8+和requests库"

坑三：API已更新但示例没跟

这是最严重的坑。API从v1升级到v2，参数名改了、返回格式变了，但文档里的示例还是v1的。开发者复制示例，得到一个404或者陌生的错误格式，完全不知道出了什么问题。

正确做法：将代码示例纳入API变更同步流程，API改了示例必须跟着改

策略一纳入自动化测试。API改了，测试会先报错，你就有机会在发布前更新示例。

策略二示例与版本绑定。标注"本示例适用于API v2.3.0及以上版本"。API升级后，读者和审校人都能从版本信息判断示例是否还适用。

策略三季度实际运行验证。我们团队第一次季度审校就发现4个有问题的示例——2个API版本问题，1个依赖变更，1个语法错误。

我有一个习惯：写完代码示例后，不是在脑子里"过一遍"觉得没问题就行，而是打开终端，复制粘贴，实际跑一遍。这个动作大概花5分钟，但它帮我避免过无数次"复制示例直接报错"的尴尬。

一句话记住这篇

写完代码示例打开终端跑一遍，再提交

📖 下一篇预告（完结篇）

被动语态：谁在操作？系统还是我？

本文由 AI 协助整理润色

更多技术文档写作干货

文档不头疼

👆 欢迎关注公众号