使用自顶向下方法在Java中设计API-编写Javadoc是最佳起点吗？

Question

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

这是处理事情的最好方法吗？我开始感到API文档应该是第一个被淘汰的-即使在编写第一个.java文件之前。这有几个优点：

1. API设计人员可以完成设计和规范，然后将实现分为几个实现者。
2. 更加灵活-设计更改不需要在Java文件中四处寻找所需的位置来编辑Javadoc注释。

还有其他人对此表示赞同吗？如果是这样，您将如何着手进行API设计？

此外，有没有什么工具可能会有所帮助？可能甚至某种基于注释的工具会生成文档，然后生成框架源（类似于模型到代码生成器）？我遇到了Eclipse PDE
API工具

-但这特定于Eclipse插件项目。我没有找到更通用的东西。

Answer 1

对于API（以及许多类型的IMO问题），一种自上而下的方法来进行问题分区和分析是必经之路。

但是（这只是基于我个人经验的2c，所以花点时间看），专注于Javadoc部分是一件好事， 但这还不够
，不能可靠地做到这一点。起点。实际上，这是非常面向实现的。那么，在此之前发生的设计，建模和推理发生了什么（可能简短）？

您必须进行某种建模来识别组成您的API的实体（名词，角色和动词）。而且，无论人们希望有多“敏捷”，如果没有清晰的问题说明（即使它只是一张10K脚的视图），也无法原型化这些东西。

最好的起点是指定您要实现的目标，或更确切地说，是您的API要解决的问题类型。BDD可能会有所帮助（以下更多内容）。也就是说，您的API将提供什么（数据元素），向谁执行什么动作（动词）以及在什么条件下（上下文）。这样就可以确定哪些实体提供这些东西以及在哪些角色下（接口，特别是具有单个清晰角色或功能的接口，而不是包罗万象的方法包）。这就导致了对它们如何一起组织（继承，组成，授权等）的分析。

一旦有了这些，就 可以 开始编写一些 初步的
Javadoc。然后，您可以开始实施那些角色的这些接口。随后有更多Javadoc（除了可能不属于Javadoc的其他文档，即教程，how-tos等）。

您将以用例，可验证的需求以及行为说明来开始实施，每种行为应单独或协同执行。BDD在这里将非常有帮助。

在进行工作时，您希望通过一些度量标准（循环复杂度 和 LCOM的某些变体）不断进行重构。这两个告诉您应该在哪里重构。

API的开发不应与应用程序的开发本质上有所不同。毕竟，API 对用户（恰好具有开发角色）是一种 实用的 应用程序。

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

Google已经在youtube上上传了其“ Google Tech
Talk”视频讲座系列。其中一个是一个小时的讲座，标题为“如何设计一个好的API及其重要性”。您可能还需要检查一下。

一些对您可能有用的链接：

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

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

“ Practical API
Design”一书的网站配套内容：http :
//wiki.apidesign.org/wiki/Main_Page

回到基础-
结构化设计＃凝聚力和耦合：http
:
//en.wikipedia.org/wiki/Structured_Design#Structured_Design