什么时候API过度设计？

Question

我鄙视使用过度设计的API，这些API并不简单。尽管如此，我正在为一个开源库设计一个API，我开始觉得我陷入了过度工程陷阱。我当然无法确定，因为当然，我写了一些令人讨厌的东西，所以它的工作原理对我来说比其他任何人都更明显。从开发人员的角度来看，您的API可能过度设计有哪些警告信号？

Answer 1

“从开发人员的角度来看，您的API可能过度设计会有什么警告信号？”

没有用例。

如果您无法完成简单的“执行此操作”方案，那么您并未设计出考虑特定用例的有用API。

您的文档应该是那些用例。

不直接解决用例的功能可能过度工程化。

Answer 2

你应该查看Joshua Bloch撰写的Google Tech Talk How To Design A Good API and Why it Matters ......他介绍了很多这些内容。

Answer 3

我发现一个非常有用的技巧，它在过去帮助我编写doc代码之前，期间和之后。

在设计供其他人使用的API时，我通常在编写代码之前记录设计。如果我过度设计设计，那么设计规范通常会充满冲突和废话。

在编码过程中，我通常会删除类定义和函数体，并开始为它们编写doxygen注释。在评论中我将有用例，示例代码和接口的假设。在此阶段，在编写太多实际代码之前，类接口通常会多次重新设计。我知道当样本代码难以编写时我已经过度工程了，我很难解释界面。当您尝试向人们解释如何使用API​​时，会暴露并消除许多糟糕的设计构思。

编码后，我将注释中的示例代码替换为从单元测试中复制的实际编译和测试代码，并进一步记录接口的行为。过度工程化的另一个迹象是当我的单元测试无法跟上界面变化时，因为有太多的移动部件和太多的方法来做同样的事情和单元测试以指数比例增长。

Answer 4

当公共api调用的堆栈跟踪要求您滚动屏幕以查看整个事件时。

Answer 5

在审阅文档和示例时，讨论与自身相关的API的措辞百分比，与讨论其应用于可信用例的措词的百分比相比较。

Answer 6

正如S.Lott所说，用例。他们将确定您的API究竟应该用于做什么。如果您设计API以完成一个非常明确的特定目标 - functionally coherent - 您很可能最终会在API中使用易于使用和理解的API或组件。

设计API应该像设计用户界面一样。大多数UI的概念都可以被API所接受，例如，KISS原则甚至是Kaizen。

我会链接到那些UI概念，但我是新用户，因此他们不会让我发布超过1个超链接。那里的好例子：StackOverflow，在发布之前告诉我们;）。

Answer 7

立即浮现在脑海中的两个（相关）问题：

• 是否有可以通过多种方式完成的事情？
• API上的方法/属性是否可以用API的其余部分表示？

更难回答，而不是过度工程本身的迹象，但绝对表明API并不像现在这么简单：

• 是否还有其他可以引入的方法/属性可以删除超过您介绍的内容（基于其他两个问题）

Answer 8

当它如此聪明以至于没有其他人能理解它。

Answer 9

当你拥有一个包含大量功能的大型API时会开始担心，经过仔细检查，这些功能会变成更简单的操作。具有高比例的组合机制与原语的API通常是一个很好的设计。

（API设计非常类似于语言设计，在这里我基本上支持Scheme理念 - 而不是将更多例程堆积到API中，简化它并包含使组合机制不再需要额外例程。）

Answer 10

使用API​​时： （1）比仅仅使用底层技术更安全，更复杂，效率更低，可预测性更低 （2）在安全性，可扩展性或跨平台自由度方面没有显着优势。

Answer 11

根据我的经验，您可以判断整个项目何时被搁置数月，等待API完成。