API 设计

命名

命名是编写可读,可维护代码的重要部分。以下最佳实践可帮助你实现这个目标。

使用一致的术语。

在你的代码中,同样的东西要使用同样的名字。如果之前已经存在的 API 之外命名,并且用户已经熟知,那么请继续使用这个命名。

的目的是充分利用用户已经知道的内容。这里包括他们所了解的问题领域,所熟悉的核心库,以及你自己 API 那部分。基于以上这些内容,他们在使用之前,不需要学习大量的新知识。

避免 缩写。

只使用广为人知的缩写,对于特有领域的缩写,请避免使用。如果要使用,请 正确的指定首字母大小写

推荐 把最具描述性的名词放到最后。

最后一个词应该是最具描述性的东西。你可以在其前面添加其他单词,例如形容词,以进一步描述该事物。

考虑 尽量让代码看起来像普通的句子。

当你不知道如何命名 API 的时候,使用你的 API 编写些代码,试着让代码看起来像普通的句子。

考虑 使用命令式动词短语命名一个函数或方法,若果你希望它的执行能被重视。

避免 在方法命名中使用 get 开头。

推荐 使用 to___() 来命名把对象的状态转换到一个新的对象的函数

一个转换函数返回一个新的对象,里面包含一些原对象的状态,但通常新对象的形式或表现方式与原对象不同。核心库有一个约定,这些类型结果的方法名应该以 to 作为开头。

如果要定义一个转换函数,遵循该约定是非常有益的。

list.toSet();
stackTrace.toString();
dateTime.toLocal();

推荐 使用 as___() 来命名把原来对象转换为另外一种表现形式的函数

转换函数提供的是“快照功能”。返回的对象有自己的数据副本,修改原来对象的数据不会改变返回的对象中的数据。另外一种函数返回的是同一份数据的另外一种表现形式,返回的是一个新的对象,但是其内部引用的数据和原来对象引用的数据一样。修改原来对象中的数据,新返回的对象中的数据也一起被修改。

这种函数在核心库中被命名为 as___()

var map = table.asMap();
var list = bytes.asFloat32List();
var future = subscription.asFuture();

避免 在方法或者函数名称中描述参数。

在调用代码的时候可以看到参数,所以无需再次显示参数了。

list.add(element);
map.remove(key);