SpecMD — 如果你的文档就是代码会怎样？

Source: Dev.to

问题

在软件开发中，保持文档与代码同步是最大的痛点之一。

文档往往会：

• 过时
• 被忽视
• 与实际代码不一致
• 难以维护
• 很少被信任

而代码则是：

• 真相的来源
• 可靠的
• 很少能立即被理解

这两个世界不必分离。

SpecMD 方法

SpecMD 是一种方法，文档使用 Markdown 编写，而该 Markdown 成为软件行为的唯一真相来源。

核心思想

1. 用纯文本写出预期的行为和规则。
2. 这些文本会变成可执行代码。
3. 代码验证实现是否与文档匹配。

如果文档与实现出现分歧：

• 测试会失败。
• 不一致会立即显现。

工作原理

• 文档中的一行可能写着：“用户的电子邮件地址在系统中必须唯一。”
• 这句话会转化为可执行的逻辑。
• 如果实现允许重复，文档会暴露出错误。

于是文档就变成了强制执行的手段。

好处

SpecMD 可以帮助以下团队：

• 构建关键系统。
• 管理大型或分布式代码库。
• 经常为新开发者进行入职培训。
• 维护复杂的业务规则。
• 需要可靠的文档可信度。
• 追求清晰性和可追溯性。

如果你曾为陈旧的文档苦恼，这将引起共鸣。

延伸阅读

• 完整写作稿：
• GitHub 开放研究项目：

讨论

• 文档是否应该在我们构建软件的过程中扮演更积极的角色？
• 描述能否转化为执行？

留下你的想法——我很想听听其他开发者在面对这个问题时的观点。