How To Design A Good API And Why It Matters

At Javapolis, Joshua Bloch gave a presentation about designing a good API. Joshua starts by defining why designing a good API matters. An API is as asset. A public API if forever. You have once chance to get it right. If it is well written, it will capture and hook customers, while a badly written one will result in an endless barrage of support calls. Good software is modular and each module should have a well defined API. A good API is one that satisfies the requirements of the appropriate audience. It is easy to learn and use while hard to misuse. The code is readable, maintainable, and extendable.

Next Joshua explains the process of API design. Gather requirements in terms of use cases. Start with a short 1 page spec. Bounce it around as many people as possible and flesh it out as you gain confidence. Then write to your API early and often, even before it’s implemented or fully specified. The code will act as examples to use in unit tests. If writing an SPI (plug-in for multiple interfaces), make sure you try on 3 different implementations. You can’t please everyone so instead aim to displease everyone equally. Expect to make mistakes and flush those out after a few years of real use.

Then Joshua covers some general principles:

· API should do one thing and do it well. Functionality should be easy to name.

· API should be as small as possible. When in doubt, leave it out, as it is easy to add it later, but you can never remove it. Look for a good power to weight ratio.

· Implementation details should not impact API

· Minimize accessibility of everything. Make classes and members as private as possible. Allow classes to be used, understood, built, tested, and debugged independently.

· Names matter. Avoid cryptic abbreviations. Be consistent. Strive for symmetry.

· Documentation matters. Document religiously. Document every class, interface, method,

constructor, parameter, and exception.

· Consider Performance consequences of API decision on performance. Bad decisions include making types mutable, using constructors instead of factories, and using implementation instead of interface



· API must coexist peacefully with platform. Obey naming conventions, avoid obsolete types, mimic patterns and take advantage of core API and language features while avoiding language pitfalls.

Next Joshua covers class design and emphasizes minimizing mutability, subclassing only when it makes sense (Liskov), and designing and document for inheritance, otherwise prohibiting it.

For method design:

· Don’t make the client do anything the module could do

· Don’t violate the principle of least astonishment

· Fail Fast- report errors as soon as possible after they occur.

· Provide programmatic access to all data available string form

· Overload with care: just because you can does not mean you should.

· Use consistent parameter ordering across methods.

· Avoid long parameter lists

· Avoid return values that demand exceptional processing: return zero length array or empty collection instead of null

Finally for exception design, throw exceptions to indicate exceptional conditions and don’t force clients to use exceptions for control flow, favor unchecked exceptions and include failure capture information in exceptions

This presentation is available on InfoQ at http://www.infoq.com/presentations/effective-api-design

Agile Quality: A Canary in a Coal Mine

At Agile 2006, Ken Schwaber gave a talk about Agile Quality. Ken starts by describing the way product owners and teams should work. He mentions some statistics showing that on average, 35% of requirements change and 65% of what is delivered is rarely or never used. So product owners have to be skilled in requirements management and make sure the product backlog focuses on the highest value, importance, and risk stories 1st.
Traditionally customers have no visibility into what’s happening until the project is almost done.
In iterative developments, customers have visibility into the project and can control risk
Every sprint, some cumulative business value is delivered. At some point, enough ROI is achieved that the customer can get rid of functionality of lowered earned value.

Ken moves on to describe the place that product owners and teams come from using waterfall and discusses some of the bad techniques for delivering on time and on cost:
1.    Reduce quality
2.    Change definition of done to somewhat done and add stabilization, user acceptance, alpha and pre-release phases

Next Ken describes how scrum falls apart if these habits persist and how organizations have fallen apart because of these habits.

He starts by listing some of quality reduction techniques:
1.    Overtime (studies shows that increasing a working day increases defects)
2.    Cut unit testing, acceptance, and performance testing
3.    Skip design and code reviews
4.    Don’t follow standards
5.    Don’t refactor

These techniques lead to a scrum only including analysis, design, coding and some testing. Every sprint something is left behind and not done. Instead it should be optimized so that in every sprint everything is done. Ask the team to define done for every sprint and daily scrum. And done should include everything.

Ken mentions that a major problem most organization face is how to add new functionality tied to legacy system or to synchronize new functionality to core functionality. The main problem is that the core functionality has no test harness, is very fragile (a simple change breaks something else), and usually only few people still know and are willing to work on it. Thus, the velocity of core functionality team is a lot less than velocity of new functionality team.

Investigating this problem further reveals that as teams bend to pressure to meet dates, they drop quality and deliver incremental crap, and within 4 or 5 years, the team’s velocity is down all the way to 1 because the software is in such bad shape.

Ken emphasizes that we should have the courage to do the right thing and not drop quality. Dropping quality to meet a date is not a customer or product owner decision. It’s a CFO decision because of the impact on the company. Software is an organizational asset and decision to cut quality must be made by executive management and reflected in financial statements.

To get out of this mess, companies end up rebuilding core functionality into each function, building new stuff and not worrying about core functionality, dropping functionality, or allocating more developers to the core team in an attempt to build up and increase the velocity of core functionality.

To undo these habits, Ken suggests that the ScrumMaster teaches the product owner how to manage by value and that he not allow the team to present anything that is not done. The CEO should be apprised of the root cause of the problem and should provide support.

Ken finishes by giving an example of SCRUM being used at Primavera and concludes that one should have the courage to do the right thing and that it is a professional responsibility that makes you feel better and is for the good of the company.
This presentation is available on InfoQ at http://www.infoq.com/presentations/agile-quality-canary-coalmine