API设计：灵活性与便于使用

Question

在编写将在各种用例中被许多其他代码使用的模块的库或公共API时，平衡灵活性和易用性的最佳方法是什么？我相信这两者经常发生冲突，你制造的东西越灵活，就越难以让它做任何特定的事情。

例如，C ++ STL使用迭代器，IMHO是非常低级别并且很烦人，但作为交换，它们非常灵活，允许相同的代码在各种STL容器上运行。另一个例子是Java标准库的设计理念，与Python标准库相比，它具有设计用于最大模块性和灵活性的小型，非常特定的类，它偏向于更平坦的类层次结构，这使得处理常见用例更简单。这些事情应该如何平衡？

Answer 1

我认为您需要考虑图书馆的目标受众 - 如果您正在编写一个经验不足的开发人员可能会使用的图书馆，您必须考虑如何帮助他们。在C ++ STL的情况下，大多数使用它们的开发人员可能不介意额外的机​​制，因为他们已经习惯了它们并且更加重视灵活性。

您可能需要考虑通过API进行两层访问，其中包含一个简单的级别和一个允许更多控制的层。但是你可能希望在你达到那个长度之前先看看框架是如何发展的。

Answer 2

如果您是标准组织的一部分，可以在其他人身上强制使用您的课程，那么您可以灵活而复杂地使用（例如stl）。

对于其他所有人来说，除非有一些非常有说服力的理由，否则易用性应始终是您的首选。否则，很少有人会使用您的代码/ API。如果使用其他人的代码的学习曲线很高，那么大多数人会选择重新实现他们需要的部分。这通常会更快，问题也更容易解决。

在我看来，在评估代码质量时，“易于理解”仅仅是“正确工作”的第二名。

如此底线，如果增加灵活性是以易于学习和使用为代价的，那么在确保灵活性是必要的之前不要增加灵活性。

Answer 3

我喜欢.NET基类库API。该库的设计大部分遵循these guidelines.

在阅读这些内容以及随附的书籍时，我学到了几个关键知识：

1. API的设计考虑到现代编辑具有智能感知能力。更长的名称是可以接受的，因为您可以标记完整的类和方法名称。这与C风格的函数相反，其名称较短，模糊，如strnicmp()

2. 使用Create，Set，Call模式：始终有一个默认的，没有参数构造函数。提供可以按任何顺序设置的属性，然后允许调用方法。使用此模式允许对象在短时间内处于无效状态。 （在调用构造函数之后，但在设置任何属性之前）但这没关系。您可以通过抛出异常来传达API滥用。这使得使用该课程更加平易近人。