接口是什么？广义的说，在设计软件时，软件与外部系统的一切交互称为接口，比如“用户接口”（GUI, 一个图形界面的程序，提供的用户操作界面），命令行接口（CUI，就是命令行程序的用法），提供外部系统调用的应用开发接口（API/SDK），提供的配置文件、环境变量等等。本文主要讨论狭义的接口即开发包提供的API。
如果软件分为多个模块（或多个端，典型的如前端与后端），那么每个模块又对其它模块提供调用接口，习惯上称之为内部接口。内部和外部是相对的，比如一个模块内，又分了若干子模块，那么该模块又具有一些内部接口；这些接口对每个子模块来说，就相当于是外部接口。
那么该不该对接口建立文档呢？应该以什么原则建立文档？
一般来说，如果有多人参与项目，尤其是模块是分布式的，建立创建接口文档，便于协作。典型的是通过网络进行通讯的若干子模块，如一个产品中有客户端（比如.net编写的桌面应用），移动客户端（安卓/苹果原生程序），服务端（比如用java编写，后面连接数据库），管理控制台（比如使用html/js编写的Web应用）等，尤其这些是不同编程语言写出的系统，其相互的调用接口，如果不写接口文档，难道要写html代码的前端开发去打开后端的java源码来查询吗？
在这种情况下，接口很好的为多人合作开发提供了降低复杂度的方法，只要接口稳定，调用者和被调用者就能免去很多相互干扰的因素，加快开发进度。
接口需要有文档来记录。
我见过很多小团队的产品根本没有文档，遇到接口不明确时都是直接找代码，看似省确很多事，实则为之后的维护埋下了雷。
文档也应纳入版本控制。
原始文档应该使用文本类型。某个改动是谁做的，因为什么原因做的，只有应用了版本控制才能方便的做到问题追源。使用文本类型的文档（比如markdown, wiki等格式），一则方便比较版本间改动，二则可以生成html, word, pdf等多种美观格式。我见过有好多团队是使用word来写文档的，由于是二进制格式，不利于版本比较，也不专业。还有好多在文档在顶部还标有版本历史，以及是谁编辑的做了哪些修改这些内容，真的没必要（除非是特别重大的变化希望读者知晓），随便用svn, git等版本工具就可以做的更专业。
文档要在没有歧义的基础上足够简洁。
很多文档描述很多，而真正有价值的内容并不会增加很多。比如参数或字段的描述，如果从名字就能很清楚的知晓它的含义，又何必再写一遍（或翻译一遍）呢，白白增加了很多开销，维护也麻烦了很多。文档不应浮于形式，而是力求只写最有价值的内容。做好这一点的关键是作者与读者要有足够的约定，比如蚕茧法就能很好的帮助简化类型定义的描述。
应有机制保证接口文档与代码的一致。
一些团队在文档上应付差事浮于形式，在代码写完后，补一个word文档应付。在更新代码时，文档没有及时更新，导致文档都是错误没法看。好的做法都应先有设计再写代码，比如架构师或主程先设计好接口，然后再开始编程实现，在实现中发现问题再修正接口，更新设计文档，而不应是写完代码再补个设计。而在文档更新的具体做法上，也流行一种做法即文档以注释的方式内嵌于代码中，我称之为“格式化注释”，这样做到设计与代码在一起，更新也就更自然的同步了。之后再通过工具将注释抽出来美化给读者看。
网友评论