Designing an API in Java using a top-down approach. Is a Javadoc entry the best starting point?

Question

Whenever I need to develop a Java API, I usually start by opening my IDE and creating packages, classes, and interfaces. Implementations of the method are all fictitious, but javadocs are detailed.

Is this the best way to go for something? I am starting to feel that the API documentation should be the first to be released - even before the first .java file is written. This has several advantages:

• An API designer can complete development and specification, and then split the implementation between several developers.
• More flexible - design changes do not require a rebound among java files that are looking for a place to edit javadoc comments.

Are there others who share this opinion? And if so, how do you get started with developing an API?

Also, are there any tools that can help? Probably even some kind of annotation-based tool that generates documentation and then a skeleton source (like generators from model to code)? I came across the Eclipse PDE API - but this is typical for Eclipse plugin projects. I did not find anything more general.

Answer 1

For the API (and for many types of IMO problems), a down-down approach for breaking down and analyzing problems is the way to go.

However (and this is just my 2c, based on my own personal experience, so take it with a piece of salt), focusing on the parts of the Javadoc is good, but this is still not enough, and cannot be a reliable starting point. In fact, it is very implementation oriented. So what happened to the design, modeling, and reasoning that were supposed to happen before that (no matter how brief it is)?

You need to do some modeling to identify the entities (nouns, roles, and verbs) that make up your API. And no matter how “mobile” you would like to be, such things cannot be prototyped without a clear picture of the problem statement (even if it's just a look at 10 thousand feet).

The best starting point is to indicate what you are trying to implement, or rather what problems your API is trying to handle. BDD can help (more on this below). That is, what your API will provide (data element elements) and to whom, by performing what actions (verbs) and under what conditions (context). This then leads to determining which entities provide these things and for which roles (interfaces, in particular, interfaces with a single, understandable role or function, and not as bags with bags). This leads to an analysis of how they are combined (inheritance, composition, delegation, etc.).

Once you do this, you will probably be in a good position to start doing the preliminary Javadoc. Then you can start working on the implementation of these interfaces, from those roles. This is followed by Javadoc (in addition to other documentation that may not appear in Javadoc.ie. Guides, instructions, etc.)

You begin your implementation by using cases and verifiable requirements and behavioral descriptions of what each thing should do on its own or in collaboration. BDD will be very useful here.

When you work, you are constantly reorganizing, I hope, accepting some indicators (cyclic complexity and some variant of LCOM). These two tell you where you should reorganize.

API development should not inherently differ from application development. After all, an API is a utilitarian application for a user (who has a development role.)

As a result, you do not have to handle API technology in any way from general software application engineering. Use the same methods, customize them according to your needs (which everyone who works with the software should), and you will do your best.

Google has been uploading a series of Google Tech Talk video lectures to youtube for quite some time now. One of them is an hour-long lecture entitled "How to create a good API and why it matters . " You can also check it out.

Some links for you that may help:

Google Tech Talk "Beyond Test Development: Behavior-Driven Development": http://www.youtube.com/watch?v=XOkHh8zF33o

Behavior- Driven Development: http://behaviour-driven.org/

Companion Website for Practical Design API: http://wiki.apidesign.org/wiki/Main_Page

Returning to the Basics - Structured Design # Cohesion and Communication: http://en.wikipedia.org/wiki/Structured_Design#Structured_Design

Answer 2

First, the definition of an interface is a contract-based programming style for declaring preconditions, postconditions and invariants. I find it goes well with Test-Driven-Development (TDD), because first you write down invariants and postconditions, this is a behavior that your tests can test.

As an aside, it seems that TDD development, developed by behavior, arose because of programmers who were not used to the interface before.

Answer 3

As for myself, I always prefer to start by writing interfaces along with their documentation and only then start with implementation.

In the past, I took a different approach, which started with UML and then using automatic code generation. The best tool I've come across on this issue is Rational Rose , which is not free, but I'm sure there are many free plugins and utils. The advantage of Rational Rose over other designers that I came across was that you can “attach” the design to your code, and then change either the code or the design, and update the other.

Answer 4

I jump directly with the prototype coding. All necessary interfaces will appear soon, and you will be able to form your proto into the final product. Get feedback along the way from who will use your API if you can.

There is no “best way” approach to developing an API, whatever works for you. Knowledge of the domain also has a large role to play.

Answer 5

I am a great fan of programming for the interface. It forms a contract between developers and users of your code. Instead of diving directly into the code, I usually start with the basic model of my system (UML diagrams, etc., depending on complexity). This is not only good documentation, but also a visual explanation of the structure of the system. With this, making code a lot easier. Such project documentation also makes it easier to understand the system when you return to it after 6 months or try to fix errors :) Prototyping also has its merits, but be prepared to throw it away and start again.