下面我们将详细描述每一个步骤开发者需要做哪些事情。这些事情包括一个代码块的编写或者创建了多少个类以及一些其他相关的工作。对于上面的例子,我们可进行如下描述:
步骤 | 工作内容 |
---|---|
创建一个图标对象 | 创建一个BMap.Icon实例。传递一个图片路径、指定图片的宽和高、指定图片的锚点位置(即哪个点对应实际的坐标点)。相关工作都是和BMap.Icon相关的,没有涉及其他内容,这里仅需要一行代码。 |
创建一个标注,并设置其图标 | 创建一个BMap.Marker实例。传递一个坐标点,并指定使用的图标对象。仅需要一行代码 |
向地图添加标注 | 调用Map.addOverlay方法,将标注实例作为参数,添加到地图上。需要一行代码 |
经过上面一番描述,API的工作单元可通过如下方式描述:
- 如果用户编写的代码包含在一个本地的代码块中,并且代码可以递增式的完成,那么工作单元可描述为本地递增式(local incremental)。
- 如果用户编写的代码包含在多个代码块中,或者代码需要多个类来交互完成,那么工作单元可描述为并行式(parallel)。
- 如果用户编写的代码既不是本地递增式也不是并行式,而是处于一种中间状态,那么工作单元可描述为功能式(functional)。
可以看出创建自定义标注的过程是本地的递增式的
Progressive Evaluation
To what extent can partially completed code be executed to obtain feedback on code behavior?
这个维度描述了开发者在编写每个任务的过程中,是否很容易的停下来并检查自己的进度完成情况。
- 如果开发者在写完每一行代码就能够停下来评估进度,那么API支持单行代码级别的评估。
- 如果开发者在写完两个或更多任务的代码后才能评估自己某一项任务的进度,那么API支持功能级别的评估。
- 如果开发者需要同时使用多个类,并要求类之间的状态要保持某种一致性,这样才能查看自己的工作进度,那么该API支持并行模块级别的评估。
我们还拿上面添加自定义标注的任务来举例,它最接近第二种情况。因为在创建icon和marker实例后,开发者并不能看到目前已经编写的代码是否OK,他/她需要执行第三个步骤,
即把标注添加到地图上之后才能看到整体的代码是否正确。
Premature commitment
wiki上的解释为:
Are there strong constraints on the order with which tasks must be accomplished?
Are there decisions that must be made before all the necessary information is available?
Can those decisions be reversed or corrected later?
微软将其改为如下说法:
To what extend does a developer have to make decisions before all the needed information is available?
开发者在使用API完成任务之前,有时不得不提前思考一些问题,比如使用API的哪些接口完成任务,它们之间有何联系,调用顺序是怎样的等等。那么开发者的思考代价有多大呢?
是在写代码之前就能轻松得出结论,还是写了一些验证性的代码之后才可以,还是整个代码都写得差不多了才发现当初思考的方式并不正确,需要重头再来?
如果开发者在使用API过程中经常遇到最后一种情况,那么就认为该API含有过多的不合理的约束(我对premature commitment的理解)。
比如API约束了调用顺序,约束了接口之间的某种调用关系,并且这些约束是一般开发者不能提前思考清楚的。
比如地图API里可以给标注添加一个标题,当鼠标移到这个标注上时,就会显示这个标题,实际上,这是给标注的DOM容器元素增加了title属性。开发者在使用过程中可能会使用下面的写法:
var marker = new BMap.Marker(map.getCenter()); // 创建一个标注对象,并给定一个坐标点 marker.setTitle("百度大厦"); // 标注创建完了,给它加个标题 map.addOverlay(marker); // 好了,添加到地图上
当我们把鼠标移到标注上,“百度大厦”四个字并没有显示,哪出问题了?API文档那个上明明写了这个接口的作用呀?实际上,只有下面的写法才能实现: