4 Minor Cons

將API設(shè)計(jì)描述放在實(shí)現(xiàn)類注釋(comment)中，然后通過工具解析抽取并生成文檔是保持文檔和代碼同步的最便捷方式，也更容易集中于一點(diǎn)進(jìn)行維護(hù)，但靈活度會(huì)收到原有語言語法的限制。

前者對(duì)于強(qiáng)類型語言的實(shí)現(xiàn)方案比較合適，而使用結(jié)構(gòu)化的文本來描述API設(shè)計(jì)，則更靈活，唯一的不足可能文檔的更新同步某些時(shí)候會(huì)不夠及時(shí)，當(dāng)然， 如果完全遵循API design and documentation的思路和流程，則可以盡可能的規(guī)避這一不足。

對(duì)于實(shí)現(xiàn)和API規(guī)范同步的問題， 一種思路是根據(jù)API規(guī)范生成測(cè)試集， 然后“打到”最終實(shí)現(xiàn)，如果不通過，則要求要么更新API規(guī)范，要么更新代碼實(shí)現(xiàn)。 這樣， 可以基本可以保證二者的同步。當(dāng)然，這樣的做法其實(shí)更像是先實(shí)現(xiàn)，后出API規(guī)范文檔， 與API設(shè)計(jì)和文檔化驅(qū)動(dòng)的做法還是有些差異的。