问题描述
限时送ChatGPT账号..每当我需要用 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 的其他文档，即教程、操作方法等)
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 是用户(碰巧具有开发角色)的实用应用程序.
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.
Google 在 YouTube 上上传其Google Tech Talk"视频讲座系列已有一段时间了.其中一个是长达一小时的讲座，标题为如何设计一个好的 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.
一些可能对您有所帮助的链接:
Some links for you that might help:
Google Tech Talk 的超越测试驱动开发:行为驱动开发":http://www.youtube/watch?v=XOkHh8zF33o
Google Tech Talk's "Beyond Test Driven Development: Behaviour Driven Development" : http://www.youtube/watch?v=XOkHh8zF33o
行为驱动开发:http://behaviour-driven/
实用 API 设计"一书的网站伴侣:http://wiki.apidesign/wiki/Main_Page
Website Companion to the book "Practical API Design" : http://wiki.apidesign/wiki/Main_Page
回归基础 - 结构化设计#Cohesion 和耦合:http://en.wikipedia/wiki/Structured_Design#Structured_Design
Going back to the Basics - Structured Design#Cohesion and Coupling : http://en.wikipedia/wiki/Structured_Design#Structured_Design
这篇关于用自顶向下的方法在 Java 中设计 API - 编写 Javadoc 是最好的起点吗?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
更多推荐
[db:关键词]
发布评论