Practical API Design (eBook)

Jaroslav Tulach is the founder and initial architect of NetBeans, later acquired by Sun Technologies. As creator of the technology behind NetBeans, he is still with the project to find ways to improve the design skills among all the programmers who contribute to the success of NetBeans open source project.

Contents at a Glance 4
Contents 6
About the Author 12
Acknowledgments 13
Prologue: Yet Another Design Book? 14
API Design Is Different 15
Who Should Read This Book? 18
Is This Book Useful Only for Java? 19
Learning to Write APIs 22
Is This Book Really a Notebook? 23
Theory and Justification 25
The Art of Building Modern Software 29
Rationalism, Empiricism, and Cluelessness 29
Evolution of Software So Far 31
Gigantic Building Blocks 33
Beauty, Truth, and Elegance 34
More Cluelessness! 36
The Motivation to Create an API 39
Distributed Development 39
Modularizing Applications 41
It’s All About Communication 46
Empirical Programming 47
The First Version Is Always Easy 49
Determining What Makes a Good API 51
Method and Field Signatures 51
Files and Their Content 52
Environment Variables and Command-Line Options 53
Text Messages As APIs 55
Protocols 56
Behavior 58
I18N Support and L10N Messages 59
Wide Definition of APIs 60
How to Check the Quality of an API 60
Ever-Changing Targets 65
The First Version Is Never Perfect 65
Backward Compatibility 66
The Importance of Being Use Case Oriented 75
API Reviews 78
Life Cycle of an API 79
Incremental Improvements 83
Practical Design 88
Do Not Expose More Than You Want 91
A Method Is Better Than a Field 92
A Factory Is Better Than a Constructor 93
Make Everything Final 95
Do Not Put Setters Where They Do Not Belong 96
Allow Access Only from Friend Code 97
Give the Creator of an Object More Rights 101
Do Not Expose Deep Hierarchies 105
Code Against Interfaces, Not Implementations 108
Removing a Method or a Field 109
Removing or Adding a Class or an Interface 110
Inserting an Interface or a Class into an Existing Hierarchy 110
Adding a Method or a Field 111
Comparing Java Interfaces and Classes 112
In Weakness Lies Strength 113
A Method Addition Lover’s Heaven 114
Are Abstract Classes Useful? 116
Getting Ready for Growing Parameters 117
Interfaces vs. Classes 119
Use Modular Architecture 120
Types of Modular Design 122
Intercomponent Lookup and Communication 125
Writing an Extension Point 138
The Need for Cyclic Dependencies 139
Lookup Is Everywhere 143
Overuse of Lookup 147
Separate APIs for Clients and Providers 151
Expressing API/SPI in C and Java 151
API Evolution Is Different from SPI Evolution 153
Writer Evolution Between Java 1.4 and 1.5 154
Split Your API Reasonably 165
Keep Testability in Mind 169
API and Testing 170
The Fade of the Specification 172
Good Tools Make Any API Easier 174
Test Compatibility Kit 176
Cooperating with Other APIs 179
Beware of Using Other APIs 179
Leaking Abstractions 183
Enforcing Consistency of APIs 184
Delegation and Composition 188
Prevent Misuses of the API 196
Do Not Overuse the JavaBeans Listener Pattern 200
Runtime Aspects of APIs 204
Fixing Odyssey 206
Reliability and Cluelessness 209
Synchronization and Deadlocks 211
Preparing for Reentrant Calls 234
Memory Management 237
Declarative Programming 243
Make Objects Immutable 245
Immutable Behavior 249
Compatibility of Documents 250
Daily Life 254
Extreme Advice Considered Harmful 256
An API Must Be Beautiful 257
An API Has to Be Correct 258
An API Has to Be Simple 259
An API Has to Have Good Performance 261
An API Must Be 100 Percent Compatible 262
An API Needs to Be Symmetrical 265
Paradoxes of API Design 266
API Doublethink 267
The Invisible Job 270
Overcoming the Fear of Committing to a Stable API 271
Minimizing Maintenance Cost 274
Evolving the API Universe 277
Resuscitating Broken Libraries 278
Conscious vs. Unconscious Upgrades 284
Alternative Behavior 288
Bridges and the Coexistence of Similar APIs 293
Teamwork 306
Organizing Reviews Before Committing Code 306
Convincing Developers to Document Their API 309
Big Brother Never Sleeps 311
Accepting API Patches 315
Using Games to Improve API Design Skills 318
Overview 318
Day 1 319
Day 2 332
Day 3: Judgment Day 340
Play Too! 347
Extensible Visitor Pattern Case Study 348
Abstract Class 351
Preparing for Evolution 353
Default Traversal 355
Clean Definition of a Version 357
Nonmonotonic Evolution 359
Data Structure Using Interfaces 360
Client and Provider Visitors 361
Triple Dispatch 364
A Happy End for Visitors 366
Syntactic Sugar 366
End-of-Life Procedures 369
The Importance of a Specification Version 370
The Importance of Module Dependencies 370
Should Removed Pieces Lie Around Forever? 373
Splitting Monolithic APIs 374
The Future 377
Principia Informatica 378
Cluelessness Is Here to Stay 379
API Design Methodology 380
Languages Ready for Evolution 382
The Role of Education 384
Share! 386
Bibliography 387
Index 388