使用自上而下的方法设计 Java API - 编写 Javadoc 是最好的起点吗？
每当我需要用 Java 设计 API 时，我通常都会先打开 IDE，然后创建包、类和接口。方法实现都是虚拟的，但 javadoc 很详细。
这是处理事情的最佳方式吗？我开始觉得 API 文档应该是第一个被制作出来的——甚至在第一个 .java 文件写出来之前。这有几个优点：
- API 设计者可以完成设计和开发。规范，然后将实现分割给几个实现者。
- 更灵活——设计的改变不需要在java文件之间来回寻找编辑javadoc注释的地方。
还有其他人同意这个观点吗？如果是这样，您如何开始 API 设计？
此外，是否有任何工具可以提供帮助？甚至可能是某种基于注释的工具，它生成文档，然后生成框架源（有点像模型到代码生成器）？我遇到了 Eclipse PDE API 工具 - 但这是特定于 Eclipse 插件项目的。我没有找到更通用的东西。
Whenever I have the need to design an API in Java, I normally start off by opening up my IDE, and creating the packages, classes and interfaces. The method implementations are all dummy, but the javadocs are detailed.
Is this the best way to go about things? I am beginning to feel that the API documentation should be the first to be churned out - even before the first .java file is written up. This has few advantages:
- The API designer can complete the design & specification and then split up the implementation among several implementors.
- More flexible - change in design does not require one to bounce around among java files looking for the place to edit the javadoc comment.
Are there others who share this opinion? And if so, how do you go about starting off with the API design?
Further, are there any tools out there which might help? Probably even some sort of annotation-based tool which generates documentation and then the skeleton source (kind of like model-to-code generators)? I came across Eclipse PDE API tooling - but this is specific to Eclipse plugin projects. I did not find anything more generic.
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（5）
对于 API（以及许多类型的问题，我认为），采用自上而下的方法进行问题划分和分析是可行的方法。
然而（这只是我根据我个人经验得出的 2c，因此请持保留态度），专注于其中的 Javadoc 部分是一件好事，但这仍然不够，并且不能可靠地作为起点。事实上，这是非常注重实施的。那么在此之前应该进行的设计、建模和推理（无论多么简短）发生了什么？
您必须进行某种建模来识别构成 API 的实体（名词、角色和动词）。无论人们想要多么“敏捷”，如果没有清晰的问题陈述图片（即使只是 10K 英尺的视图），这些事情就无法原型化。
最好的起点是指定您要做什么正在尝试实现，或者更准确地说，您的 API 正在尝试解决什么类型的问题。 BDD 可能会有所帮助（更多内容见下文）。也就是说，您的 API 将提供什么（数据元素），以及向谁提供什么操作（动词）以及在什么条件下（上下文）。这导致识别哪些实体提供这些东西以及在什么角色下提供这些东西（接口，特别是与单个、明确的角色或功能的接口，而不是作为包罗万象的方法包）。这导致了对它们如何编排在一起的分析（继承、组合、委托等）。
一旦你有了这些，那么你可能就可以开始做一些初步< /em> Javadoc。然后您可以开始致力于这些接口、这些角色的实现。接下来是更多 Javadoc（除了可能不属于 Javadoc 的其他文档，即教程、操作方法等）。
您可以从用例和可验证的需求以及每件事应单独或协作执行的行为描述开始实施。 BDD 在这里会非常有帮助。
当你工作时，你会不断地重构，希望通过采取一些指标（圈复杂度和 LCOM 的一些变体）。这两个告诉你应该在哪里重构。
API 的开发不应与应用程序的开发本质上不同。毕竟，API 对于用户（恰好具有开发角色）来说是一个实用的应用程序。
因此，您不应将 API 工程与一般软件密集型应用程序工程区别对待。使用相同的做法，根据您的需要调整它们（每个使用软件的人都应该这样做），您会做得很好。
谷歌在 YouTube 上上传其“Google Tech Talk”视频讲座系列已经有一段时间了。其中一个是长达一小时的讲座，标题为“如何设计良好的 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
For an API (and for many types of problems IMO), a top-down approach for problem partitioning and analysis is the way to go.
However (and this is just my 2c based on my own personal experience, so take it with a grain of salt), focusing on the Javadoc part of it is a good thing to do, but that is still not sufficient, and cannot reliably be the starting point. In fact, that is very implementation oriented. So what happened to the design, the modeling and reasoning that should take place before that (however brief that might be)?
You have to do some sort of modeling to identify the entities (the nouns, roles and verbs) that make up your API. And no matter how "agile" one would like to be, such things cannot be prototyped without having a clear picture of the problem statement (even if it is just a 10K foot view of it.)
The best starting point is to specify what you are trying to implement, or more precisely, what type of problems your API is trying to address. BDD might be of help (more of that below). That is, what is it that your API will provide (datum elements), and to whom, performing what actions (the verbs) and under what conditions (the context). That leads then to identify what entities provide these things and under what roles (interfaces, specifically interfaces with a single, clear role or function, not as catch-all bags of methods). That leads to an analysis on how they are orchestrated together (inheritance, composition, delegation, etc.)
Once you have that, then you might be in a good position to start doing some preliminary Javadoc. Then you can start working on the implementation of those interfaces, of those roles. More Javadoc follows (in addition to other documentation that might not fall within Javadoc .ie. tutorials, how-tos, etc.)
You start your implementation with use cases and verifiable requirements and behavioral descriptions of what each thing should do alone or in collaboration. BDD would be extremely helpful here.
As you work on, you continuously refactor, hopefully by taking some metrics (cyclomatic complexity and some variant of LCOM). These two tell you where you should refactor.
A development of an API should not be inherently different from the development of an application. After all, an API is a utilitarian application for a user (who happens to have a development role.)
As a result, you should not treat API engineering any diferently from general software-intensive application engineering. Use the same practices, tune them according to your needs (which every one who works with software should), and you'll do fine.
Google has been uploading its "Google Tech Talk" video lecture series on youtube for quite some time. One of them is an hour long lecture titled "How To Design A Good API and Why it Matters". You might want to check it out also.
Some links for you that might help:
Google Tech Talk's "Beyond Test Driven Development: Behaviour Driven Development" : http://www.youtube.com/watch?v=XOkHh8zF33o
Behavior Driven Development : http://behaviour-driven.org/
Website Companion to the book "Practical API Design" : http://wiki.apidesign.org/wiki/Main_Page
Going back to the Basics - Structured Design#Cohesion and Coupling : http://en.wikipedia.org/wiki/Structured_Design#Structured_Design
首先定义接口是声明前置条件、后置条件和不变量的契约式编程风格。我发现它与测试驱动开发（TDD）结合得很好，因为您首先编写的不变量和后置条件是您的测试可以检查的行为。
顺便说一句，TDD 的行为驱动开发阐述似乎是由于程序员没有习惯性地首先考虑接口而产生的。
Defining the interface first is the programming-by-contract style of declaring preconditions, postconditions and invariants. I find it combines well with Test-Driven-Development (TDD), because the invariants and postconditions you write first are the behaviours that your tests can check for.
As an aside, it seems the Behaviour-Driven-Development elaboration of TDD seems to have come about because of programmers who did not habitually think of the interface first.
就我自己而言，我总是更喜欢从编写接口及其文档开始，然后才开始实现。
过去我采用了另一种方法，即从 UML 开始，然后使用自动代码生成。
对于这个问题，我遇到的最好的工具是 Rational Rose，它不是免费，但我确信有很多免费的插件和实用程序。
与我遇到的其他设计器相比，Rational Rose 的优点是您可以将设计“附加”到您的代码，然后修改代码或设计，另一个将更新。
As for my self, I always prefer starting with writing the interfaces along with their documentation and only then start with the implementation.
In the past I took another approach which was starting with the UML and then using the automatic code generation.
The best tool I encountered for this matter was Rational Rose which is not free but I'm sure there are plenty of free plugins and utils.
The advantage of Rational Rose over other designers I bumped into was that you can "attach" the design to your code and then modify on either code or design and the other will update.
我非常喜欢界面编程。它在代码的实现者和用户之间形成了契约。
我通常从系统的基本模型（UML 图等，取决于复杂性）开始，而不是直接深入代码。这不仅可以作为良好的文档，而且还提供了系统结构的直观说明。有了这个，编码部分就变得更容易了。这种设计文档也让你在 6 个月后重新审视系统或尝试修复错误时更容易理解系统:)
原型设计也有其优点，但要准备好扔掉它并重新开始。
I'm a great fan of programming to the interface. It forms a contract between the implementors and the users of your code.
Rather than diving straight into code, I usually start with a basic model of my system (UML diagrams etc, depending on the complexity). Not only does this serve as good documentation, it provides a visual clarification of the system structure. Having this makes the coding part much easier to do. This kind of design documentation also makes it easier to understand the system when you come back to it in 6 months, or try to fix bugs :)
Prototyping also has its merits, but be prepared to throw it away and start again.
我直接开始使用原型进行编码。任何需要的界面很快就会出现在您面前，您可以将原型塑造成最终产品。如果可以的话，从任何将要使用你的 API 的人那里获取反馈。
没有“最好的方法”来进行 API 设计，做任何对你有用的方法。领域知识也可以发挥很大作用
I jump right in with the coding with a prototype. Any required interfaces soon pop out at you and you can mould your proto into a final product. Get feedback along the way from whomever is going to be using your API if you can.
There is no 'best way' of approaching API design, do whatever works for you. Domain knowledge also has a large part to play