用自顶向下的方法在Java中设计API——编写Javadoc是最好的起点吗？

每当我需要用Java设计API时，我通常首先打开IDE，创建包、类和接口。方法实现都是虚拟的，但是Javadoc是详细的

这是处理事情的最好方式吗？我开始觉得API文档应该是第一个被大量生产出来的——甚至在第一个.java文件被编写出来之前。这几乎没有什么好处：

API设计人员可以完成设计和规范，然后在几个实现人员之间分割实现

更灵活-设计上的更改不需要在java文件中寻找编辑javadoc注释的位置

还有其他人持同样的观点吗？如果是这样的话，您如何开始API设计

---

此外，是否有任何工具可能会有所帮助？甚至可能是某种基于注释的工具，生成文档，然后生成骨架源代码（有点像模型到代码生成器）？我遇到过—但这是特定于Eclipse插件项目的。我没有发现更通用的东西。

至于我自己，我总是喜欢从编写接口及其文档开始，然后才开始实现

在过去，我采用了另一种方法，从UML开始，然后使用自动代码生成。 我遇到的最好的工具是它不是免费的，但我确信有很多免费的插件和UTIL。

---

与我遇到的其他设计师相比，Rational Rose的优势在于，您可以将设计“附加”到代码中，然后对代码或设计进行修改，另一个将进行更新。

我直接使用原型进行编码。任何需要的接口很快就会出现在您面前，您可以将您的原型塑造成最终产品。如果可以的话，从将要使用您的API的人那里获取反馈

---

没有“最好的方法”来进行API设计，做任何适合你的事情。领域知识也有很大的作用

我非常喜欢对界面编程。它在代码的实现者和用户之间形成契约。 我通常从系统的基本模型（UML图等，取决于复杂性）开始，而不是直接深入代码。这不仅可以作为良好的文档，还可以直观地说明系统结构。有了它，编码部分就容易多了。当您在6个月后再次使用该系统或尝试修复bug时，这种设计文档还可以使您更容易理解该系统：）

---

原型也有它的优点，但要准备好扔掉它，重新开始。

首先定义接口是按契约式编程，声明先决条件、后决条件和不变量。我发现它与测试驱动开发（TDD）结合得很好，因为您首先编写的不变量和后条件是您的测试可以检查的行为

另一方面，TDD的行为驱动开发精化似乎是因为程序员没有习惯性地首先考虑接口。

对于API（以及IMO中的许多类型的问题），自上而下的问题划分和分析方法是可行的

然而（这只是基于我个人经验的2c，所以请恕我直言），关注其中的Javadoc部分是一件好事，但这仍然不够，也不能作为可靠的起点。事实上，这是非常面向实现的。那么在此之前应该进行的设计、建模和推理（无论多么简短）发生了什么

您必须进行某种建模来识别构成API的实体（名词、角色和动词）。不管人们多么希望“敏捷”，如果没有问题陈述的清晰图像（即使只是10英尺的视图），这些东西都无法原型化

最好的起点是指定您试图实现什么，或者更准确地说，您的API试图解决什么类型的问题。BDD可能会有所帮助（更多信息见下文）。也就是说，API将提供什么（数据元素），向谁执行什么动作（动词）以及在什么条件下（上下文）。这将导致识别哪些实体提供这些东西，以及在哪些角色下（接口，特别是与单个、明确的角色或功能的接口，而不是像捕获所有方法一样）。这将导致分析它们是如何协调在一起的（继承、组合、委派等）

一旦有了它，您就可以开始做一些初步的Javadoc了。然后，您可以开始实现这些接口和角色。接下来还有更多的Javadoc（除了可能不属于Javadoc的其他文档，如教程、how-tos等）

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

在工作过程中，您会不断地进行重构，希望通过采用一些度量（圈复杂度和LCOM的一些变体）。这两个函数告诉您应该在哪里进行重构

API的开发不应该与应用程序的开发有本质的区别。毕竟，API对于用户来说是一个实用的应用程序（用户碰巧有一个开发角色）

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

谷歌一直在