book

Practical API Design

by Jaroslav Tulach

June 2008

Intermediate to advanced

400 pages

14h 4m

English

Apress

Read now

Unlock full access

Rationalism, Empiricism, and CluelessnessEvolution of Software So FarGigantic Building BlocksBeauty, Truth, and EleganceMore Cluelessness!

Distributed DevelopmentModularizing ApplicationsNonlinear VersioningIt’s All About CommunicationEmpirical ProgrammingThe First Version Is Always Easy
Method and Field SignaturesFiles and Their ContentEnvironment Variables and Command-Line OptionsText Messages As APIsProtocolsBehaviorI18N Support and L10N MessagesWide Definition of APIsHow to Check the Quality of an APIComprehensibilityConsistencyDiscoverabilitySimple Tasks Should Be EasyPreservation of Investment
The First Version Is Never PerfectBackward CompatibilitySource CompatibilityBinary CompatibilityFunctional Compatibility—the Amoeba EffectThe Importance of Being Use Case OrientedAPI ReviewsLife Cycle of an APIIncremental Improvements
A Method Is Better Than a FieldA Factory Is Better Than a ConstructorMake Everything FinalDo Not Put Setters Where They Do Not BelongAllow Access Only from Friend CodeGive the Creator of an Object More RightsDo Not Expose Deep Hierarchies
Removing a Method or a FieldRemoving or Adding a Class or an InterfaceInserting an Interface or a Class into an Existing HierarchyAdding a Method or a FieldComparing Java Interfaces and ClassesIn Weakness Lies StrengthA Method Addition Lover’s HeavenAre Abstract Classes Useful?Getting Ready for Growing ParametersInterfaces vs. Classes
Types of Modular DesignIntercomponent Lookup and CommunicationWriting an Extension PointThe Need for Cyclic DependenciesLookup Is EverywhereOveruse of Lookup
Expressing API/SPI in C and JavaAPI Evolution Is Different from SPI EvolutionWriter Evolution Between Java 1.4 and 1.5Split Your API Reasonably
API and TestingThe Fade of the SpecificationGood Tools Make Any API EasierTest Compatibility Kit
Beware of Using Other APIsLeaking AbstractionsEnforcing Consistency of APIsDelegation and CompositionPrevent Misuses of the APIDo Not Overuse the JavaBeans Listener Pattern
Fixing OdysseyReliability and CluelessnessSynchronization and DeadlocksDocument the Threading ModelPitfalls of Java MonitorsDeadlock ConditionsDeadlock TestTesting Race ConditionsAnalyzing Random FailuresAdvanced Usage of LoggingExecution Flow Control Using LoggingPreparing for Reentrant CallsMemory Management
Make Objects ImmutableImmutable BehaviorCompatibility of Documents
An API Must Be BeautifulAn API Has to Be CorrectAn API Has to Be SimpleAn API Has to Have Good PerformanceAn API Must Be 100 Percent CompatibleAn API Needs to Be Symmetrical
API DoublethinkThe Invisible JobOvercoming the Fear of Committing to a Stable APIMinimizing Maintenance Cost
Resuscitating Broken LibrariesConscious vs. Unconscious UpgradesAlternative BehaviorBridges and the Coexistence of Similar APIs
Organizing Reviews Before Committing CodeConvincing Developers to Document Their APIBig Brother Never SleepsAccepting API Patches
OverviewDay 1Problem of Nonpublic API ClassesThe Immutability ProblemThe Problem of the Missing ImplementationThe Problem of Possibly Incorrect ResultsSolutions for Day 1Day 2I Want to Fix My Mistakes ProblemSolutions for Day 2Day 3: Judgment DayConclusionsPlay Too!
Abstract ClassPreparing for EvolutionDefault TraversalClean Definition of a VersionNonmonotonic EvolutionData Structure Using InterfacesClient and Provider VisitorsTriple DispatchA Happy End for VisitorsSyntactic Sugar
The Importance of a Specification VersionThe Importance of Module DependenciesShould Removed Pieces Lie Around Forever?Splitting Monolithic APIs
Principia InformaticaCluelessness Is Here to StayAPI Design MethodologyLanguages Ready for EvolutionThe Role of EducationShare!

Content preview from Practical API Design

CHAPTER 12

Declarative Programming

An interesting way to minimize the problems that arise with runtime aspects of an API is to eliminate the runtime completely. For lack of a better name, let’s call this declarative programming, though the term is overloaded with various meanings and it might mean different things to different people. With declarative programming, the basic idea is that users of your API don’t describe step-by-step what they want your API to do. Rather, they “declare” what they want to have happen and then rely on your API to do it when necessary.

IS THERE REALLY SUCH A THING AS DECLARATIVE PROGRAMMING?

When I first learned about ...