什么时候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

我发现一个非常有用的技巧，它在过去对我很有帮助，那就是在编写代码之前、期间和之后编写文档。

在设计供其他人使用的API时，我通常在编写代码之前对设计进行文档记录。如果我过度设计设计，设计规范通常充满了冲突和无稽之谈。

在编码过程中，我通常会清除类定义和函数体，并开始为它们编写doxygen注释。在注释中，我将提供用例、示例代码和对接口的假设。在这个阶段，在编写太多真正的代码之前，类接口通常会经过多次重新设计。我知道，当示例代码很难编写，并且我很难解释界面时，我已经过度工程了。当你试图向人们解释如何使用你的API时，很多糟糕的设计思想都会暴露出来，并被消除。

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