用自上而下的方法用Java设计API – 写Javadoc是最好的起点吗？
每当我需要在Java中设计API时，我通常会先打开我的IDE，然后创建包，类和接口。 方法实现都是虚拟的，但javadocs是详细的。
这是最好的办法吗？ 我开始觉得API文档应该是第一个被淘汰的 – 甚至在第一个.java文件被写入之前。 这几点没什么优势：
- API设计人员可以完成设计和规范，然后在多个实现者之间拆分实现。
- 更灵活 – 设计更改不需要在java文件中反弹，寻找编辑javadoc注释的位置。
还有其他人分享这个观点吗？ 如果是这样，您如何开始使用API设计？
此外，有没有可能有帮助的工具？ 甚至可能是某种基于注释的工具，它可以生成文档，然后生成骨架源（类似于模型到代码生成器）？ 我遇到了Eclipse PDE API工具 – 但这是Eclipse插件项目特有的。 我没有找到更通用的东西。
对于API（以及IMO的许多类型的问题），问题分区和分析的自上而下方法是可行的方法。
然而（根据我自己的个人经验，这只是我的2c，所以把它当作一粒盐），专注于它的Javadoc部分是一件好事， 但这仍然是不够的 ，并且不能可靠地起点。 实际上，这是非常面向实现的。 那么在此之前应该发生的设计，建模和推理会发生什么（无论多么简短）？
您必须进行某种建模以识别构成API的实体（名词，角色和动词）。 而且无论人们想要多么“敏捷”，如果没有对问题陈述的清晰描述，这些事情就无法成为原型（即使它只是10K英尺的视图。）
最好的出发点是指定您要实现的内容，或者更准确地说，是您尝试解决的API问题类型。 BDD可能会有所帮助（以下更多内容）。 也就是说，你的API将提供什么（基准元素），向谁执行，执行什么动作（动词）以及在什么条件下（上下文）。 然后，这将导致确定哪些实体提供这些东西以及在什么角色（界面，特别是具有单一，明确的角色或function的界面，而不是全部方法包）。 这导致分析他们如何协调（inheritance，组成，授权等）
一旦你有了这个，那么你可能处于一个很好的位置，开始做一些初步的 Javadoc。 然后，您可以开始处理这些角色的接口的实现。 更多Javadoc如下（除了可能不属于Javadoc .ie。教程，how-to等的其他文档）
您可以通过用例和可validation的要求以及每个事物应该单独或协作的行为描述开始实施。 BDD在这里非常有帮助。
在您工作的过程中，您不断进行重构，希望通过采用一些指标（圈复杂度和 LCOM的一些变体）。 这两个告诉你应该在哪里重构。
API的开发不应与应用程序的开发本质上不同。 毕竟，API是用户的实用应用程序（恰好具有开发角色。）
因此，您不应该对通用软件密集型应用程序工程中的API工程进行任何处理。 使用相同的做法，根据您的需要调整它们（每个使用软件的人都应该这样做），你会做得很好。
谷歌已经在youtube上上传了他的“Google Tech Talk”video讲座系列已有一段时间了。 其中一个是一个小时的演讲题为“如何设计一个好的API及其重要性” 。 您可能还想查看它。
一些可能有用的链接：
Google Tech Talk的“超越测试驱动开发：行为驱动开发”： http ： //www.youtube.com/watch？v = XOkHh8zF33o
行为驱动的发展： http ： //behaviour-driven.org/
网站伴侣“实用API设计”一书： http ： //wiki.apidesign.org/wiki/Main_Page
回归基础 – 结构化设计＃凝聚力和耦合： http ： //en.wikipedia.org/wiki/Structured_Design#Structured_Design
首先定义接口是按合同编程的方式来声明前置条件，后置条件和不变量。 我发现它与测试驱动开发（TDD）结合得很好，因为您首先编写的不变量和后置条件是您的测试可以检查的行为。
顺便说一下，似乎行为驱动开发对TDD的阐述似乎是因为程序员没有习惯性地首先考虑接口。
至于我自己，我总是喜欢从编写接口及其文档开始，然后才开始实现。
在过去，我采用了另一种方法，从UML开始，然后使用自动代码生成。 我遇到的最好的工具是Rational Rose ，它不是免费的，但我确信有很多免费的插件和工具。 Rational Rose优于其他设计人员的优势在于，您可以将设计“附加”到代码中，然后在代码或设计上进行修改，另一个将更新。
我直接用原型编码。 很快就会出现任何所需的接口，您可以将原型制作成最终产品。 如果可以的话，从任何人将要使用您的API获取反馈。
没有“最好的方法”来接近API设计，做任何适合你的事情。 领域知识也有很大的作用
我非常喜欢界面编程。 它在实现者和代码用户之间形成契约。 我不是直接进入代码，而是从我的系统的基本模型开始（UML图等，具体取决于复杂性）。 这不仅可以作为良好的文档，还可以直观地阐明系统结构。 这样可以使编码部分更容易完成。 这种设计文档还可以让您在6个月内回归它时更容易理解系统，或者尝试修复错误:)原型设计也有其优点，但要准备好扔掉它并重新开始。