API设计:灵活性Vs。易用性

Question

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

例如，IMHO使用迭代器，C++级别非常低，使用起来很烦人，但作为交换，它们非常灵活，允许相同的代码在所有类型的STL容器上操作。另一个例子是Java标准库的设计哲学，Java标准库的小而具体的类是为最大程度的模块化和灵活性而设计的，而Python标准库偏爱更扁平的类层次结构，这使得处理常见用例变得更简单。像这样的事情应该如何平衡？

Answer 1

如果你是一个标准团体的一员，可以强制别人使用你的类，那么你可以选择灵活而复杂的(例如stl)。

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

在我看来，在评价代码的质量时，“易懂”仅次于“它能正常工作”。

所以底线是，如果增加灵活性是以易学和易用性为代价的，那么在证明灵活性是必要的之前，不要增加灵活性。

Answer 2

我认为你需要考虑这个库的目标受众-如果你正在编写一个经验较少的开发人员可能会很好地使用的库，你必须考虑如何帮助他们。在C++ STL的情况下，可能大多数使用它们的开发人员并不介意额外的机制，因为他们已经习惯了这些机制，并且更看重灵活性。

您可能希望考虑通过API的两层访问，这两层具有使事情变得简单的级别和允许更多控制的层。但您可能想先看看框架是如何开发的，然后再讲到那个部分。

Answer 3

我喜欢.NET基类库API。该库的设计主要遵循these guidelines.

在阅读这些和随附的书时，我获得了几个关键的知识片段：

1. 在设计时要牢记现代编辑器具有智能感知功能。更长的名称是可以接受的，因为您可以使用制表符来完成类和方法的名称。这与具有更短、模糊名称的C风格函数相反，例如创建、设置、调用模式的strnicmp()
2. Use :始终具有默认的、没有参数的构造函数。提供可以按任何顺序设置的属性，然后允许调用方法。使用此模式允许对象在短时间内处于无效状态。(在调用构造函数之后，但在设置任何属性之前)，但这是可以的。你可以通过抛出异常来传达API的滥用。这使得使用这个类更容易。