程序员最烦的有两件事：1、看别人的代码却没有文档；2、给自己的代码写文档。 --互联网
细心的朋友会发现，今天的“名人名言”有点特别，因为它并不是名人名言，但是作为程序员的我，却深有体会。所以，今天就来聊聊开发文档的事情，因为我用的比较多的是API，所以就说说API接口文档吧。
网上有很多关于如何写接口文档的文章，甚至，更有开发框架可以帮助自动生成文档。那么，我们究竟该如何写接口文档，让看的人明白，让写的人轻松呢？首先，需要明确的是，文档是写给人看的，所以，别人看得懂是最最重要的一点，同时，也必须要方便传播，让别人容易看到！所以，通常会使用HTML网页的形式来写开发文档，但是写HTML并不方便，好在我们还有MarkDown。
我认为，一篇好的技术文档主要应该包含下列几个要素：
- 类功能
- 函数功能说明
- 参数说明
- 返回值说明
- 错误码说明
下面我放出一个我写的接口文档的例子。纯属个人喜好，不喜勿喷！
类名：Zxblog
功能：接口文档实例
时间：2016/05/16
- 接口方法：function1
- 接口标识：Zxblog/function1
- 接口功能：测试方法- 请求参数说明
| 参数名 | 说明 | 备注 |
|---|---|---|
| a | 这是一个必要参数 | |
| b | 这是一个可选参数 | 默认值为1 |
- 返回值说明
| 参数名 | 说明 | 备注 |
|---|---|---|
| ret | 返回码 | 0表示成功，非零请对照错误码 |
| msg | 错误说明 | 请求出错才有 |
| data | 返回的数据 | 只有正确请求才有 |
- 错误码说明
| 错误码 | 含义 | 备注 |
|---|---|---|
| -1 | 非法请求 | 身份标识丢失 |
- 接口请求示例[可选]
{
"ret":0,
"data":[
{
"a":1,
"b":2
},
{
"a":1,
"b":2
}
]
}最后说两句：我觉的文档的作用在于知识的分享和传承，在开源变成主流的今天，我们会用到很多别人的代码，所以我们也要有分享的精神，如果你不想写文档，那你就想想看没有文档的代码时候自己的感受，不用复杂，寥寥几个表格，简单明了。
本文由 陌上花开 创作，采用 知识共享署名4.0 国际许可协议进行许可
本站文章除注明转载/出处外，均为本站原创或翻译，转载前请务必署名
最后编辑时间为: Jul 1, 2016 at 06:16 am