接口是什么汤善？廣義的說(shuō)，在設(shè)計(jì)軟件時(shí)牧愁，軟件與外部系統(tǒng)的一切交互稱(chēng)為接口素邪，比如“用戶接口”（GUI, 一個(gè)圖形界面的程序，提供的用戶操作界面）猪半，命令行接口（CUI兔朦，就是命令行程序的用法），提供外部系統(tǒng)調(diào)用的應(yīng)用開(kāi)發(fā)接口（API/SDK）磨确，提供的配置文件沽甥、環(huán)境變量等等。本文主要討論狹義的接口即開(kāi)發(fā)包提供的API乏奥。

如果軟件分為多個(gè)模塊（或多個(gè)端摆舟，典型的如前端與后端），那么每個(gè)模塊又對(duì)其它模塊提供調(diào)用接口邓了，習(xí)慣上稱(chēng)之為內(nèi)部接口恨诱。內(nèi)部和外部是相對(duì)的，比如一個(gè)模塊內(nèi)骗炉，又分了若干子模塊照宝，那么該模塊又具有一些內(nèi)部接口；這些接口對(duì)每個(gè)子模塊來(lái)說(shuō)句葵，就相當(dāng)于是外部接口厕鹃。

那么該不該對(duì)接口建立文檔呢？應(yīng)該以什么原則建立文檔笼呆？

一般來(lái)說(shuō)熊响，如果有多人參與項(xiàng)目，尤其是模塊是分布式的诗赌，建立創(chuàng)建接口文檔汗茄，便于協(xié)作。典型的是通過(guò)網(wǎng)絡(luò)進(jìn)行通訊的若干子模塊铭若，如一個(gè)產(chǎn)品中有客戶端（比如.net編寫(xiě)的桌面應(yīng)用）洪碳，移動(dòng)客戶端（安卓/蘋(píng)果原生程序），服務(wù)端（比如用java編寫(xiě)叼屠，后面連接數(shù)據(jù)庫(kù)）瞳腌，管理控制臺(tái)（比如使用html/js編寫(xiě)的Web應(yīng)用）等，尤其這些是不同編程語(yǔ)言寫(xiě)出的系統(tǒng)镜雨，其相互的調(diào)用接口嫂侍，如果不寫(xiě)接口文檔，難道要寫(xiě)html代碼的前端開(kāi)發(fā)去打開(kāi)后端的java源碼來(lái)查詢嗎？

在這種情況下挑宠，接口很好的為多人合作開(kāi)發(fā)提供了降低復(fù)雜度的方法菲盾，只要接口穩(wěn)定，調(diào)用者和被調(diào)用者就能免去很多相互干擾的因素各淀，加快開(kāi)發(fā)進(jìn)度懒鉴。

接口需要有文檔來(lái)記錄。

我見(jiàn)過(guò)很多小團(tuán)隊(duì)的產(chǎn)品根本沒(méi)有文檔碎浇，遇到接口不明確時(shí)都是直接找代碼临谱，看似省確很多事，實(shí)則為之后的維護(hù)埋下了雷奴璃。

文檔也應(yīng)納入版本控制悉默。

原始文檔應(yīng)該使用文本類(lèi)型。某個(gè)改動(dòng)是誰(shuí)做的苟穆，因?yàn)槭裁丛蜃龅穆笪挥袘?yīng)用了版本控制才能方便的做到問(wèn)題追源。使用文本類(lèi)型的文檔（比如markdown, wiki等格式）鞭缭，一則方便比較版本間改動(dòng)剖膳，二則可以生成html, word, pdf等多種美觀格式。我見(jiàn)過(guò)有好多團(tuán)隊(duì)是使用word來(lái)寫(xiě)文檔的岭辣，由于是二進(jìn)制格式吱晒，不利于版本比較，也不專(zhuān)業(yè)沦童。還有好多在文檔在頂部還標(biāo)有版本歷史仑濒，以及是誰(shuí)編輯的做了哪些修改這些內(nèi)容，真的沒(méi)必要（除非是特別重大的變化希望讀者知曉）偷遗，隨便用svn, git等版本工具就可以做的更專(zhuān)業(yè)墩瞳。

文檔要在沒(méi)有歧義的基礎(chǔ)上足夠簡(jiǎn)潔。

很多文檔描述很多氏豌，而真正有價(jià)值的內(nèi)容并不會(huì)增加很多喉酌。比如參數(shù)或字段的描述，如果從名字就能很清楚的知曉它的含義泵喘，又何必再寫(xiě)一遍（或翻譯一遍）呢泪电，白白增加了很多開(kāi)銷(xiāo)，維護(hù)也麻煩了很多纪铺。文檔不應(yīng)浮于形式相速，而是力求只寫(xiě)最有價(jià)值的內(nèi)容。做好這一點(diǎn)的關(guān)鍵是作者與讀者要有足夠的約定鲜锚，比如蠶繭法就能很好的幫助簡(jiǎn)化類(lèi)型定義的描述突诬。

應(yīng)有機(jī)制保證接口文檔與代碼的一致苫拍。

一些團(tuán)隊(duì)在文檔上應(yīng)付差事浮于形式，在代碼寫(xiě)完后旺隙，補(bǔ)一個(gè)word文檔應(yīng)付怯疤。在更新代碼時(shí)，文檔沒(méi)有及時(shí)更新催束，導(dǎo)致文檔都是錯(cuò)誤沒(méi)法看。好的做法都應(yīng)先有設(shè)計(jì)再寫(xiě)代碼伏社，比如架構(gòu)師或主程先設(shè)計(jì)好接口抠刺，然后再開(kāi)始編程實(shí)現(xiàn)，在實(shí)現(xiàn)中發(fā)現(xiàn)問(wèn)題再修正接口摘昌，更新設(shè)計(jì)文檔速妖，而不應(yīng)是寫(xiě)完代碼再補(bǔ)個(gè)設(shè)計(jì)。而在文檔更新的具體做法上聪黎，也流行一種做法即文檔以注釋的方式內(nèi)嵌于代碼中罕容，我稱(chēng)之為“格式化注釋”，這樣做到設(shè)計(jì)與代碼在一起稿饰，更新也就更自然的同步了锦秒。之后再通過(guò)工具將注釋抽出來(lái)美化給讀者看。

在描述接口時(shí)喉镰，可以使用蠶繭表示法來(lái)簡(jiǎn)化文檔的描述旅择，關(guān)于蠶繭表示法的詳細(xì)說(shuō)明，可以參考這里侣姆。