我鄙视使用过度设计的 API，这些 API 不会让简单的事情变得简单。尽管如此，我正在为一个开源库设计一个 API，我开始觉得自己掉进了过度工程的陷阱。我真的无法确定，因为当然，我写了这该死的东西，所以它的工作原理对我来说比其他任何人都更明显。从开发人员的角度来看，有哪些警告信号表明您的 API 可能被过度设计？
问问题
1872 次
11 回答
19
“从开发人员的角度来看，您的 API 可能被过度设计有哪些警告信号？”
没有用例。
如果您无法完成简单的“执行此操作”场景，那么您就没有考虑到特定用例来设计有用的 API。
您的文档应该是那些用例。
不直接解决用例的功能可能是过度设计的。
于 2009-06-04T02:53:46.403 回答
11
你应该看看 Joshua Bloch 的 Google Tech Talk How To Design A Good API and Why it Matters ……他涵盖了很多这些东西。
于 2009-06-04T03:16:13.350 回答
5
我发现一个非常有用的技巧，它在过去对我有帮助，那就是在编码之前、期间和之后编写文档。
在设计供其他人使用的 API 时，我通常会在编写代码之前记录设计。如果我过度设计设计，设计规范通常充满冲突和废话。
在编码过程中，我通常会删除类定义和函数体，并开始为它们编写 doxygen 注释。在评论中，我将提供接口的用例、示例代码和假设。在这个阶段，在编写太多实际代码之前，类接口通常会经过多次重新设计。我知道当示例代码很难编写并且我很难解释接口时，我已经过度工程了。当你试图向人们解释如何使用你的 API 时，许多糟糕的设计思想就会暴露出来并被淘汰。
编码后，我将注释中的示例代码替换为从我的单元测试中复制的真实编译和测试代码，并进一步记录接口的行为。过度工程的另一个迹象是当我的单元测试无法跟上接口变化时，因为有太多的移动部件和太多的方法来做同样的事情，并且单元测试以指数比例增长。
于 2009-06-04T05:35:22.397 回答
4
当一个常见 api 调用的堆栈跟踪要求您滚动屏幕以查看整个内容时。
于 2009-06-04T03:37:18.897 回答
2
在查看文档和示例时，讨论 API 本身的冗长百分比与讨论其在可信用例中的应用的冗长百分比相比较。
于 2009-06-04T02:57:20.313 回答
2
正如 S.Lott 所说，用例。他们将确定您的 API 究竟应该用于做什么。如果您设计您的 API 以完成一个非常清晰、具体的目标——功能上一致——您很可能最终会在您的 API 中得到一个既易于使用又易于理解的 API 或组件。
设计 API 应该像设计用户界面一样。API 可以包含大多数 UI 概念，例如，KISS 原则甚至 Kaizen。
我会链接到那些 UI 概念，但我是新用户，所以他们不会让我发布超过 1 个超链接。很好的例子：StackOverflow，在我们发布之前让我们知道；）。
于 2009-06-04T03:13:00.780 回答
1
立即想到要问自己的两个（相关）问题：
- 是否有不止一种方式可以完成的事情？
- API 上是否有可以用 API 的其余部分表示的方法/属性？
更难回答，本身并不是过度设计的迹象，但绝对表明 API 还没有那么简单：
- 您是否可以引入其他方法/属性，从而可以删除比您介绍的更多的内容（基于其他两个问题）
于 2009-06-04T02:52:59.353 回答
1
当它如此聪明以至于其他人无法理解时。
于 2009-06-04T03:24:11.647 回答
1
当你有一个包含大量函数的大型 API 时开始担心，这些函数在仔细检查后会证明是更简单的操作的组合。具有高组合机制与原语比率的 API 通常是一个好的设计。
（API 设计与语言设计非常相似，在这里我基本上支持 Scheme 哲学——而不是在 API 中堆积更多例程，而是简化它并包含使额外例程变得不必要的组合机制。）
于 2009-06-04T03:49:14.610 回答
0
使用 API 时：(1) 比仅使用底层技术更迟钝、更复杂、效率更低和更难预测，并且 (2) 在安全性、可扩展性或跨平台自由度方面没有显着优势。
于 2009-06-05T14:33:28.067 回答
0
根据我的经验，您可以判断整个项目何时被搁置数月，等待 API 完成。
于 2009-06-05T14:36:37.623 回答