在簡(jiǎn)單的使用場(chǎng)景中，一定要讓框架無(wú)需文檔就能使用。
- 要確保API是直觀的，無(wú)需查閱參考文檔就能用于基本場(chǎng)景
你總不希望寫(xiě)個(gè)“Hello World”都去查閱API文檔吧。
- 要為所有的API提供優(yōu)秀的文檔。
一方面，并非所有的API都能自說(shuō)明。不同的人會(huì)認(rèn)為不同的API是自說(shuō)明的；
另一方面，有些人想在開(kāi)始使用API之前完全理解它們。
設(shè)計(jì)自說(shuō)明API時(shí)最重要的一些考慮因素：
- 命名
要在規(guī)范檢查中重視標(biāo)識(shí)符名稱(chēng)的選擇；
不要擔(dān)心標(biāo)識(shí)符的名字太冗長(zhǎng)；
一眼就能看出相應(yīng)的方法是做什么的，類(lèi)型和參數(shù)是表示什么意思。
而且類(lèi)型的名字如果足夠好，那么用到這些類(lèi)型的代碼會(huì)更易于立即和維護(hù)。
要在設(shè)計(jì)過(guò)程的初期就讓用戶(hù)教育專(zhuān)家參與；
考慮把最好的名字留給最常用的類(lèi)型。
- 異常
要通過(guò)異常消息來(lái)清楚地告訴開(kāi)發(fā)人員對(duì)框架的誤用。
- 強(qiáng)類(lèi)型
很明顯，調(diào)用Customer.Name要比調(diào)用Customer.Properties["Name"]容易。
要盡可能提供強(qiáng)類(lèi)型API。
如果必須使用屬性包，那么應(yīng)該為包中最常用的屬性提供相應(yīng)的強(qiáng)類(lèi)型屬性。
- 一致性
要確保與.NET框架以及客戶(hù)可能會(huì)使用的其他框架保持一致。
- 限制抽象的數(shù)量
標(biāo)準(zhǔn)面向?qū)ο笤O(shè)計(jì)方法會(huì)產(chǎn)生大量抽象。其目的是使代碼易于維護(hù)。然而如果框架中存在太多的抽象，則會(huì)要求用戶(hù)對(duì)框架的架構(gòu)有深入的了解，不易于用戶(hù)使用。
避免在主要場(chǎng)景的API中使用太多的抽象。