其中原因很简单,由于标题是添加在DOM元素上的,那么在调用addOverlay方法之前,DOM元素并没有创建出来,setTitle发现DOM元素不存在就直接return了,也没有把这个title存起来,那么后来再添加到地图上也就看不到标题了。
这里,API就存在一个调用顺序上的约定,使用者可能在经历了失败时候才会知道这个约定,好在调整起来并不费力,至少代码没有白写。
一个好的API应该尽量减少这种不合理的约定。另外,如果想减少开发者的思考代价,一份结构清晰的文档是必不可少的。
Penetrability
How does the API facilitate exploration, analysis, and understanding of its components, and how does a targeted developer go about retrieving what is needed.
这个维度是指开发者需要理解API的底层实现细节到一个什么程度以及对这些细节的理解程度,也就是说API的透明程度(penetrability)如何。
比如,一个封装了很多底层接口的API需要使用者理解这些底层实现细节,否则API就不能正常工作。
API Elaboration
To what extend must th eAPI be adapted to meet th eneeds of a targeted developer?
开发者使用API来完成任务,其中一些任务仅仅通过调用几个API的现有接口就能完成,另一些任务可能需要继承API的一个类,并重载一些方法来完成,还有一些任务可能需要开发者自己编写接口的具体实现来完成。
这个维度描述了API暴露出来的扩展性,即API有哪些接口直接使用的,有哪些需要开发者自己继承扩展的,有哪些是开发者自行创建的。
当用户使用地图API时,有些功能可能是API中没有提供的,这时候就需要开发者自己写一些模块来处理(就像线上的百度地图)。
对于一些简单的任务,API要尽可能提供现成的接口供开发者使用。另有一部分开发者对接口的灵活性要求更高,希望通过扩展现有的API来实现自己的功能。API最好能同时满足这些不同的需求
API Viscosity
What are the barriers to change inherent in the API, and how much effort does a targeted developer need to expend to make a change.
这个维度描述了改变已写代码的容易程度,可简称为易改性。当用户发现自己代码运行错误或者发现选用的方法不对,修改起来是否足够容易呢?
这里的修改通常是指那些比较小的修改,但是一个小的修改可能会产生“多米诺”效应:一个地方的代码变动会导致另一个地方的代码需要调整,接着又会导致另一处……这就要求API在设计过程中模块划分要合理,同时处理好它们之间的耦合程度。
修改代码是不可避免的,这和我们思考行为有关系,我们会在大脑中勾画一个方案,并不断的进行调整。那些高手可直接在大脑中就想出一些中等复杂问题的解,一般人也能在大脑中直接处理一些简单的问题,而那些大型而又复杂的问题,估计没有人能够直接通过大脑就能想出解决办法。
当问题越大越复杂,API的易改性的作用就越明显。
Consistency
Once part of an API is learned, how much of the rest of it can be inferred?
一致性也是API可用性需要考虑的,我们经常会注意产品界面是否具有一致性,比如同一个网站的每个网页的菜单样式是否一样,图标风格是否一样,字体类型、颜色、大小是否一样等等。
Green在他的文章中也将这个因素描述为API的可猜测性,也就是说使用者了解了部分API的使用方法后,是否能很顺利的猜出API其他部分的使用方法。
在地图API中,本地搜索接口的使用方式为:
var myLoc = new BMap.LocalSearch(map); myLoc.search("百度大厦");
当用户了解它的使用方法后,可以很轻松的使用公交导航、驾车导航等接口。