用自上而下的方法用Java设计API - 写Javadoc是最好的起点吗？ [英] Designing APIs in Java with top-down approach - Is writing up the Javadoc the best starting point?
问题描述
每当我需要用Java设计API时，我通常会先打开我的IDE，然后创建包，类和接口。方法实现都是虚拟的，但javadocs是详细的。
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.
这是最好的方法吗？我开始觉得API文档应该是第一个被淘汰的 - 甚至在第一个.java文件被写入之前。这没什么好处：
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:
- API设计师可以完成设计和设计。规范，然后在几个实现者之间拆分实现。
- 更灵活 - 设计更改不需要在java文件中反弹，寻找编辑javadoc注释的地方。
还有其他人分享这个观点吗？如果是这样，你如何开始使用API设计？
Are there others who share this opinion? And if so, how do you go about starting off with the API design?
此外，还有哪些工具可能会有所帮助吗？甚至可能是某种基于注释的工具，它可以生成文档，然后生成骨架源（类似于模型到代码生成器）？我遇到了 Eclipse PDE API工具 - 但这是特定于Eclipse插件项目的。我没有找到更通用的东西。
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.
推荐答案
对于API（以及IMO的许多类型的问题），自上而下问题分区和分析的方法是可行的方法。
For an API (and for many types of problems IMO), a top-down approach for problem partitioning and analysis is the way to go.
然而（根据我个人的经验，这只是我的2c，所以请耐心等待），专注于Javadoc部分是一件好事，但仍然不够，并且不能可靠地成为起点。实际上，这是非常面向实现的。那么在此之前应该进行的设计，建模和推理会发生什么（无论多么简短）？
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)?
你必须做某种建模来识别构成API的实体（名词，角色和动词）。无论人们想要多么敏捷，如果没有对问题陈述的清晰描述，这些事情就不能成为原型（即使它只是10K英尺的视图。）
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.)
最好的出发点是指定您要实现的内容，或者更准确地说，是您尝试解决的API问题类型。 BDD可能会有所帮助（以下更多内容）。也就是说，你的API将提供什么（基准元素），向谁执行，执行什么动作（动词）以及在什么条件下（上下文）。然后，这将导致确定哪些实体提供这些东西以及在什么角色（界面，特别是具有单一，明确的角色或功能的界面，而不是全部方法包）。这导致分析它们如何一起编排（继承，组合，委托等）。
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.)
一旦你有了，那么你可能能够开始做一些初步 Javadoc。然后，您可以开始处理这些角色的接口的实现。接下来是更多Javadoc（除了可能不属于Javadoc .ie教程，how-to等等的其他文档）。
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.)
您可以使用用例开始实现每个事物应该单独或协作的可验证要求和行为描述。 BDD在这里非常有用。
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.
在你工作的时候，你不断重构，希望通过采取一些指标（圈复杂度和的某些变体） LCOM）。这两个告诉你应该在哪里重构。
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.
API的开发不应与应用程序的开发本质上不同。毕竟，API是用户的一个 utilitarian 应用程序（恰好具有开发角色。）
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.)
因此，你应该不要将API工程与一般的软件密集型应用工程区别对待。使用相同的做法，根据您的需要进行调整（每个使用软件的人都应该这样做），你会做得很好。
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.
谷歌一直在上传它的谷歌技术讲座关于youtube的视频讲座系列已有一段时间了。其中一个是一个小时的讲座，名为如何设计一个好的API及其重要性。您可能也想查看它。
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.
一些可能有用的链接：
Google Tech Talk's 超越测试驱动开发：行为驱动开发： http://www.youtube.com/watch？ v = XOkHh8zF33o
Google Tech Talk's "Beyond Test Driven Development: Behaviour Driven Development" : http://www.youtube.com/watch?v=XOkHh8zF33o
行为驱动开发： http： //behaviour-driven.org/
实用API设计一书的网站伴侣： http://wiki.apidesign.org/wiki/Main_Page
Website Companion to the book "Practical API Design" : http://wiki.apidesign.org/wiki/Main_Page
回到基础知识 - 结构化设计＃内聚和耦合： http://en.wikipedia.org/wiki/Structured_Design#Structured_Design
Going back to the Basics - Structured Design#Cohesion and Coupling : http://en.wikipedia.org/wiki/Structured_Design#Structured_Design
这篇关于用自上而下的方法用Java设计API - 写Javadoc是最好的起点吗？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
