向下工作法的一点思考：文档即代码

[banxi1988]

2006 的时候，amazon CTO 在一篇文章中介绍了向下工作法（或者有也有翻译成向后工作法）

https://www.allthingsdistributed.com/2006/11/working_backwards.html

向下工作法，简而言之就是下面的流程：

1. 先写宣传稿
2. 再写 FAQ
3. 再定义用户体验
4. 再写用户手册

走完这 4 步之后，对于要做的产品应该是相当的清晰了。

我看了之后深以为然。

然后分享我的一个思考：文档即代码

这一点对于前后端 API 模块的开发来说相当适用。 也就是说，正确良好的工作过程应该是，先写好 API 文档，再通过 API 文档生成前端的 JS/TS 代码。 通过 API 文档生成后端代码。

前后端的 API 模块都应该遵从这样一个逻辑。

1. 先写 API 文档。
2. 通过 API 文档生成 代码，（需要时初始手写代码）
3. 更新 API 文档
4. 再根据 API 文档更新前后端代码。
5. ...

它带来的好处：

1. API 文档和前后端的代码，能保持高度一致
2. 通过代码自动生成基本的代码，减少工作量（大部分的 Domain Model, 和 基本 API 接口请求及响应都应该自动生成）
3. 方便批量修改。

API 文档可以采用 Swagger 的文档。

[mofe]

其实就是先写测试再写代码……

[johnnie502]

BDD/TDD 请了解一下...

[virusdefender]

代码就是文档 https://strcpy.me/index.php/archives/772/

[scnace]

LZ 你要的就是 protobuf 啊 BDD 和 TDD 对业务密集型的应用感觉还是有点勉强 不知道大家是怎么做的

[BearD01001]

亚马逊先发软文再开发了解一下？

[janxin]

@scnace 还好吧，勉强在哪里？

[TommyLemon]

根据文档生成代码，已经有开源方案了
<img src="http://apijson.org">

后端接口和文档自动化，前端(客户端) 定制返回 JSON 的数据和结构！
<img src="https://github.com/TommyLemon/APIJSON">
创作不易，GitHub 右上角点 Star 支持下吧，谢谢^_^

[Raymon111111]

业务逻辑复杂到一定得有文档

很常见

[kurtchen]

等写起来会发现文档有时候也不是那么详尽；特别是大型应用

[lastpass]

然而实际情况是 用户改需求了。
md 又要改代码又要改文档。

[feverzsj]

文档是不可能写的，项目结束都不可能写文档的，写了也没用，不写的话，公司反而更依赖你

[zhengxiaowai]

理想很好啊，现实很残酷

[lastpass]

什么，还有一周项目就要交付了。
我们一行代码都没有写。
管项目的领导你心里没点笔数吗?
先做出个 demo 去应付一下吧。
文档?我 demo 都不一定能写完。

[tingyunsay]

@feverzsj 哈哈，以后跳槽交接的时候能交接半年 o(￣ε￣*)

[feverzsj]

@tingyunsay 辞职顶多一个月，公司没有权力不让你跳槽

[zhaogaz]

不知道有什么可思考的，前人的书里面早就写了，多看看书

[ml1344677]

测试驱动开发啊 快速开发原型

[ofooo]

楼主，请问怎么根据文档 api 自动生成代码？ api 用什么写？
还是说只是先有了文档 api 再手工写代码？

[chenyu8674]

PM：”销售已经跟客户那边把牛逼吹出去了，这需求你们技术必须得做，怎么实现我不管，明天上线“

向下工作法+敏捷开发，天朝领先世界几十年（ doge ）

[banxi1988]

@ofooo #18 比如你用 swagger 的文档格式描述 API 的话。
1 ） swagger 官方网站 本身提供了一系列的工具可以生成各种前后端代码。
2 ）可根据 API 文档 (json 格式，或 yaml 格式）生成（前后端代码）。

我自己也再做生成前后端代码的脚本。前端脚本基本实现过了。 后端要等等（因为最近没做后端）

[specita]

理想很美好，现实.... 首先你得有一群能实践你想法的队友...

[shyangs]

老外就没遇过需求都讲不清楚，说明天要验收的 PM 呀

::doge::

[mcfog]

个人更倾向反过来，代码生成文档，毕竟让程序员写代码和让程序员写文档的难度差了不止一个数量级

[A555]

客户：虽然我想做什么都不知道，但是你必须要满足我。
我我不知道我要做成什么样啊，不然我找你们干嘛