符合Swift API设计指南

Question

通过阅读当前的API设计指南对我来说并不明显，以下哪个版本更好。

class MediaLoader {}
class MediaRequest {}

let mediaLoader = MediaLoader()
let mediaRequest = MediaRequest()

// Option 1
mediaLoader.add(request: mediaRequest)

// Option 2
mediaLoader.add(mediaRequest: mediaRequest)

// Option 3
mediaLoader.addRequest(mediaRequest)

// Option 4
mediaLoader.add(mediaRequest)

上述哪一项最符合当前的API设计指南？

Answer 1

答案实际上取决于MediaLoader的目的和语义。如果MediaLoader只是mediaRequests的集合，则.add（mediaRequest）是要走的路，因为它会在语境上流动并在上下文中有意义。

另一方面，如果mediaRequest只是导致其目的的许多不同事物之一，那么.add（）本身就不会传达足够的上下文来正确阅读该语句。例如，如果你还可以添加显示通道或过滤器，那么仅仅说.add（某事）就不够清楚了。这是您使用描述关系的扩展名称。例如.addRequest（），addChannel（），addFilter（）。

但不是.add（请求：...），因为使用第一个参数的名称并不是区分关系的理想方式。应该使用它来澄清执行添加的方法或访问请求的方式。这将为最常见和最简单的用例留下“无名”变体。例如.add（fromTemplate：webRequesTemplate）或.addRequest（fromTemplate：webTemplate）。