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

Question

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

这是最好的办法吗？我开始觉得API文档应该是第一个被淘汰的 - 甚至在第一个.java文件被写入之前.这没什么好处:

1. API设计人员可以完成设计和规范,然后在多个实现者之间拆分实现.
2. 更灵活 - 设计更改不需要在java文件中反弹,寻找编辑javadoc注释的位置.

还有其他人分享这个意见吗？如果是这样,您如何开始使用API​​设计？

此外,有什么工具可以帮助吗？甚至可能是某种基于注释的工具,它可以生成文档,然后生成骨架源(类似于模型到代码生成器)？我遇到了Eclipse PDE API工具 - 但这是Eclipse插件项目特有的.我没有找到更通用的东西.

Answer 1

对于 API（以及许多类型的问题，我认为），采用自上而下的方法进行问题划分和分析是可行的方法。

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

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

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

一旦掌握了这些，您就可以开始做一些初步的Javadoc 了。然后您可以开始致力于这些接口、这些角色的实现。接下来是更多 Javadoc（除了可能不属于 Javadoc 的其他文档，即教程、操作方法等）

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

当你工作时，你会不断地重构，希望通过采取一些指标（圈复杂度和LCOM 的一些变体）。这两个告诉你应该在哪里重构。

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

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

谷歌在 YouTube 上上传其“Google Tech Talk”视频讲座系列已经有一段时间了。其中之一是一个长达一小时的讲座，标题为“如何设计一个好的 API 及其重要性”。您可能也想检查一下。

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

Google 技术讲座的“超越测试驱动开发：行为驱动开发”：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