Practical API Design

PART 1: Theory and Justification -- CHAPTER 1 The Art of Building Modern Software -- Rationalism, Empiricism, and Cluelessness -- Evolution of Software So Far -- Gigantic Building Blocks -- Beauty, Truth, and Elegance -- More Cluelessness! -- CHAPTER 2 The Motivation to Create an API -- Distributed Development -- Modularizing Applications -- It's All About Communication -- Empirical Programming -- The First Version Is Always Easy -- CHAPTER 3 Determining What Makes a Good API -- Method and Field Signatures -- Files and Their Content -- Environment Variables and Command-Line Options -- Text Messages As APIs -- Protocols -- Behavior -- I18N Support and L10N Messages -- Wide Definition of APIs -- How to Check the Quality of an API -- CHAPTER 4 Ever-Changing Targets -- The First Version Is Never Perfect -- Backward Compatibility -- The Importance of Being Use Case Oriented -- API Reviews -- Life Cycle of an API -- Incremental Improvements -- PART 2: Practical Design -- CHAPTER 5 Do Not Expose More Than You Want -- A Method Is Better Than a Field -- A Factory Is Better Than a Constructor -- Make Everything Final -- Do Not Put Setters Where They Do Not Belong -- Allow Access Only from Friend Code -- Give the Creator of an Object More Rights -- Do Not Expose Deep Hierarchies -- CHAPTER 6 Code Against Interfaces, Not Implementations -- Removing a Method or a Field -- Removing or Adding a Class or an Interface -- Inserting an Interface or a Class into an Existing Hierarchy -- Adding a Method or a Field -- Comparing Java Interfaces and Classes -- In Weakness Lies Strength -- A Method Addition Lover 's Heaven -- Are Abstract Classes Useful? -- Getting Ready for Growing Parameters -- Interfaces vs. Classes -- CHAPTER 7 Use Modular Architecture -- Types of Modular Design -- Intercomponent Lookup and Communication -- Writing an Extension Point -- The Need for Cyclic Dependencies -- Lookup Is Everywhere -- Overuse of Lookup -- CHAPTER 8 Separate APIs for Clients and Providers -- Expressing API/SPI in C and Java -- API Evolution Is Different from SPI Evolution -- Writer Evolution Between Java 1.4 and 1.5 -- Split Your API Reasonably -- CHAPTER 9 Keep Testability in Mind -- API and Testing -- The Fade of the Specification -- Good Tools Make Any API Easier -- Test Compatibility Kit -- CHAPTER 10 Cooperating with Other APIs -- Beware of Using Other APIs -- Leaking Abstractions -- Enforcing Consistency of APIs -- Delegation and Composition -- Prevent Misuses of the API -- Do Not Overuse the JavaBeans Listener Pattern -- CHAPTER 11 Runtime Aspects of APIs -- Fixing Odyssey -- Reliability and Cluelessness -- Synchronization and Deadlocks -- Document the Threading Model -- Pitfalls of Java Monitors -- Preparing for Reentrant Calls -- Memory Management -- CHAPTER 12 Declarative Programming -- Make Objects Immutable -- Immutable Behavior -- Compatibility of Documents -- PART 3: Daily Life -- CHAPTER 13 Extreme Advice Considered Harmful -- An API Must Be Beautiful -- An API Has to Be Correct -- An API Has to Be Simple -- An API Has to Hav.