InfoQReview

From APIDesign

Revision as of 12:09, 18 February 2009

What was the motivation behind writing the "Practical API Design" book?

This book is based on notes that I have collected over the last ten years, while designing and maintaining NetBeans APIs and transferring this knowledge to the rest of our developers. I started to think about converting my notes into a book five years ago, but it took long time before I really started. Either I had other tasks to do, or I was afraid of not being able to finish such book, afraid of being refused by publisher, etc.

However in summer 2007, at one family garden party, I met my wife's cousin and when I told him about my doubts, he said: "So you know what to write about, you know that it is an interesting topic, you know that you are an expert in it, and you are still not writing!?".

I always reminded his comment whenever my motivation to finish the "Practical API Design" book weakened.

PS: I'd like to thank everyone who helped me finish my book: http://thanks.apidesign.org/

You discussed the Component Injection technique to achieve a

Modular Architecture. What role design concepts like Dependency Injection

(DI), Aspect-Oriented Programming (AOP), and Annotations can play in

software development in general and API design in particular?

I believe that modularizing our applications into pieces is very desirable. It is even better if the pieces are unaware of each other and there is someone who assembles them together. To allow such assembly of loosely coupled pieces one desperately needs some form of injection. DI in the Spring style is fine. java.util.ServicesLookup works as well. I dedicated Chapter 7 to compare those and other alternatives.

There used to be time when people went nuts when they heard about bytecode manipulations. This is no longer true, people are not afraid to execute different bytecode than the one produced by Java compiler, yet if you tell them to go directly into the .class file and manipulate the bits the fear will be back. Why is that? I believe this is due to AOP. In fact AOP can be seen as a highlevel language for bytecode manipulations. It is not that power as if change the .class file directly, yet it is approachable to masses and generally understandable. I guess it is a perfect example showing that good abstractions make everything more usable. This is true in the world of bytecode manipulations as well as in API design.

You wrote

in the book about how to check the quality of an API library. Can you

elaborate on how the teams can have an on-going assessment and validation

of the quality of software being written?

There is a common wisdom among programmers saying that design cannot be done by committee. However how can we design bigger and bigger systems without designing in teams? Does not that hurt consistency? Yes, partially. Most people seem to be able to keep design consistency when they work alone, however software projects of today and of the future are designed by teams. Keeping consistency in such environment is much harder, but it is possible.

As usually, one has two choices: either detect regressions in quality when they happen, or prevent such problems before they are integrated. I have dedicated full Chapter 16 to this topics. It describes what aspects need to be verified and checked, and how to check them automatically. This can warn us when something goes bad. Also it introduces an "API Review" process which the NetBeans team is using to do review API changes before integration.

How can Agile and lean

software development methodologies like SCRUM, XP and Kanban help a project

team involved in the design and development of API frameworks?

The question is whether agile methodologies help design and development of API frameworks, or whether properly modularizing an application and splitting it into many libraries with APIs makes use of agile methodologies easier? Both is likely true.

There are some good rules in the world of API design. You need to be ready that first version is never perfect. You need to envision your users. Unit test coverage is almost a must. One should be ready for evolution.

Many of the above advices are close to big rules of agile methodologies. As such I think that proper API design and agile methodologies can only strengthen together.

Can you

discuss how your team conducted architecture and design reviews in NetBeans

development project?

We have two modes. Standard review and Fast-Track review. The latter one is used for small, incremental, compatible, non-controversial changes. It is based on "optimistic locking strategy": one prepares the code change diff and attaches it to our issue tracking system. People then have a week to comment or veto the change. If nobody objects, it can be applied then. This works well for single method or class extensions to already existing libraries.

The Standard review is more targeted to reviewing a whole new library or subsystem. It is two round review. First of all we review the concept, and if accepted the result is then reviewed again before integration to main code repository.

All the gory details are available at http://openide.netbeans.org/tutorial/reviews/

What are the best practices and "gotchas" that

software architects should keep in mind when working on creating reusable

component libraries?

It slightly hard to enumerate them all, it took me 400 pages in the Practical API Design book. But let's pick up something inspiring:

What do you think the term API includes? Names of classes? Probably. Names of their fields or methods? Indeed, if they are public or protected. Is that all?

No, it is not. Did you ever think about the files your application reads as an API? About open sockets being an API? Environment variables? Localized messages? Text output that it produces? This all can influence the behaviour of your application/library and also can be observed externally. As such, it is some kind of API. It is important to realize that and keep that in mind.

What is the role of software architects in the

current economic and market conditions?

Tough question. The general answer is to learn to offer what the market desperately needs. But I suspect nobody is really sure what it is. Except...

One of the problems in software development is associated with "big bang" changes - e.g. situations when you find out that your product has too many bugs, design problems that it is unfixable and it needs complete rewrite. Finding this out takes some time, usually the evidence needs to grow over few releases, but there is a point of time in lifecycle of most of software projects when someone offers to perform "bigbang" change. This is usually refused at first, as everyone understands such rewrite will be painful and costly. Yet over next few releases, when the evidence strengthens, the team realizes there is no escape. At that time the whole project is stopped, an incompatible rewrite of some subsystem is put in and then the rest of teams adopts to such change. In spite how realistic plans were, this usually takes much longer and at the end we can have a new shiny product which is less buggy but handles just about a half of the functionality of the old one. Needs less to say that this is not effective at all.

The Practical API Design book describes best practices to avoid need for such "big bang" changes. First of all it explains what compatibility is and advocates small, incremental, backward compatible changes, always focusing on future evolution. Such mode does not need distruptive "big bang" changes at all. On the other hand, sometimes they are necessary. That is why the book discusses ways to provide alternative co-existent behaviours and explains how to bridge them together, if necessary.

If we modularize our applications and treat each piece as a library with an API, we can minimize the need for stop-the-world "big bang" rewrites and replace them with continuous distributed improvements. This is may be slightly more expensive at first, but in the long term cost of ownership is definitely lower.

All that said leads to following answer to your original question. Maybe software architects should learn more about proper API design and use it to create more cost effective product teams.

What do you think about the new

features and APIs in the upcoming JDK Version 7 and the dropped features

like Closures?

The #1 thing that Java needs is a standard module system adopted by everyone. Recently I was arguing with a Ruby guy about benefits of API design in Ruby. Originally it looked like "duck typing" is the big advantage, but then we found out that real advantage is that Ruby has gems with all the library dependencies and Java has nothing. This needs to be fixed.

I know there are existing module systems. Btw. one of them runs behind NetBeans, but by no means each library in the world is designed with modularity in mind. This has to be changed, there needs to be support for modularity in the Java language itself. I am even willing to wait next few years for closures, if I can get the modularity in the Java now.

If you have to pick a feature that you like the most in

Java language, what would it be? And the feature that you least like about?

Java is said to have many weaknesses. However I guess one of its weaknesses is also its biggest strength.

Java is said to be verbose. True, you can write shorter programs doing the same in many other languages. So Java is verbose. However the benefit is that people can not only write the program, but also read it. Java programs can be read and understood. Moreover this can be done on a printed page, without "go declaration" and "code completion" in an IDE.

I guess I am not satisfied how verbose Java is. But I am really glad that it is readable.

Lastly, other than your own book, do you have an IT and a non-IT book

recommendation for our readers?