java - 使用自上而下的方法在 Java 中设计 API - 编写 Javadoc 是最好的起点吗？

Question

每当我需要用 Java 设计 API 时，我通常会先打开我的 IDE，然后创建包、类和接口(interface)。方法实现都是虚拟的，但 javadoc 很详细。

这是解决问题的最佳方式吗？我开始觉得 API 文档应该是第一个被搅动出来的——甚至在第一个 .java 文件被编写之前。这有几个优点:

1. API 设计者可以完成设计和规范，然后将实现拆分给几个实现者。
2. 更灵活 - 设计更改不需要在 java 文件中来回寻找编辑 javadoc 注释的位置。

还有其他人同意这个观点吗？如果是这样，您如何着手进行 API 设计？

此外，是否有任何可能有用的工具？甚至可能是某种基于注释的工具生成文档然后生成骨架源代码(有点像模型到代码生成器)？我遇到了Eclipse PDE API tooling - 但这是特定于 Eclipse 插件项目的。我没有找到更通用的内容。

Answer 1

对于 API(以及 IMO 的许多类型的问题)，自上而下的问题划分和分析方法是必经之路。

然而(这只是基于我个人经验的 2c，所以请对它持保留态度)，专注于它的 Javadoc 部分是一件好事，但这仍然不是足够，并且不能可靠地作为起点。事实上，这是非常面向实现的。那么在此之前应该进行的设计、建模和推理(无论多么简短)发生了什么？

您必须进行某种建模以识别构成 API 的实体(名词、角色和动词)。而且，无论人们希望变得多么“敏捷”，如果没有清晰的问题陈述图(即使只是 10K 英尺的 View )，就无法对此类事物进行原型(prototype)设计。

最好的起点是指定您要尝试实现什么，或者更准确地说，您的 API 试图解决什么类型的问题。 BDD 可能会有所帮助(更多内容见下文)。也就是说，您的 API 将提供什么(基准元素)，向谁提供，执行什么操作(动词)以及在什么条件下(上下文)。然后，这导致确定哪些实体提供这些东西以及在什么角色下(接口(interface)，特别是与单一、明确的角色或功能的接口(interface)，而不是包罗万象的方法包)。这导致分析它们是如何协调在一起的(继承、组合、委托(delegate)等)

一旦有了它，您可能就可以开始做一些初步 Javadoc。然后你可以开始着手实现那些接口(interface)，那些角色。接下来是更多 Javadoc(除了可能不属于 Javadoc 的其他文档之外。即教程、操作方法等)

您从用例和可验证的要求以及每件事情应该单独或协作完成的行为描述开始实现。 BDD 在这里会非常有用。

随着您的工作，您不断重构，希望通过采用一些指标(圈复杂度和 LCOM 的一些变体)。这两个告诉你应该在哪里重构。

API 的开发不应与应用程序的开发本质上不同。毕竟，API 是用户(恰好具有开发角色)的实用应用程序。

因此，您不应将 API 工程与一般的软件密集型应用程序工程区别对待。使用相同的做法，根据您的需要调整它们(每个使用软件的人都应该这样做)，您会做得很好。

Google 在 youtube 上上传其“Google Tech Talk”视频讲座系列已经有一段时间了。其中之一是一个小时的讲座，标题为"How To Design A Good API and Why it Matters"。 .您可能还想检查一下。

一些可能对您有帮助的链接:

Google Tech Talk 的“超越测试驱动开发:行为驱动开发”:http://www.youtube.com/watch?v=XOkHh8zF33o

行为驱动开发:http://behaviour-driven.org/

“实用 API 设计”一书的网站伴侣:http://wiki.apidesign.org/wiki/Main_Page

回到基础 - 结构化设计#Cohesion and Coupling:http://en.wikipedia.org/wiki/Structured_Design#Structured_Design