The Design Process -

The Design Process -

API Design CPSC 315 Programming Studio Spring 2009 Follows Kernighan and Pike, The Practice of Programming and Joshua Blochs Library-Centric Software Design 05 Keynote Talk: How to Design a Good API and Why It Matters API Application Programming Interface Source code interface For library or OS Provides services to a program

At its base, like a header file But, more complete Why is API Design Important? Company View Can be asset big user investment in learning and using Bad design can be source of long-term support problems

Once used, its tough to change Especially if there are several users Public APIs One chance to get it right Characteristics of Good APIs Easy to learn Easy to use even without documentation Hard to misuse Easy to read and maintain code that uses it Sufficiently powerful to satisfy requirements

Easy to extend Appropriate to audience Designing an API Gather requirements Dont gather solutions Extract true requirements Collect specific scenarios where it will be used Create short specification Consult with users to see whether it works Flesh it out over time

Hints: Write plugins/use examples before fully designed and implemented Expect it to evolve Broad Issues to Consider in Design 1. Interface The classes, methods, parameters, names 2. Resource Management

How is memory, other resources dealt with 3. Error Handling What errors are caught and what is done Information Hiding How much detail is exposed Impacts all three of the above 1. Interface Principles Simple

General Regular Predictable Robust Adaptable Simple Users have to understand! Do one thing and do it well Functionality should be easy to explain As small as possible, but never smaller Conceptual weight more important than providing

all functionality Avoid long parameter lists Choose small set of orthogonal primitives Dont provide 3 ways to do the same thing General Implementation can change, API cant Hide Information! Dont let implementation detail leak into API Minimize accessibility (e.g. private classes and members)

Implementation details can confuse users Be aware of what is implementation Dont overspecify behavior of modules Tuning parameters are suspect Regular Do the same thing the same way everywhere Related things should be achieved by related means Consistent parameter ordering, required inputs Functionality (return types, errors, resource management)

Names matter Self explanatory Consistent across API Same word means same thing in API Same naming style used Consistent with related interfaces outside the API Predictable Dont violate the principle of Least Astonishment

User should not be surprised by behavior Even if this costs performance Dont reach behind the users back Accessing and modifying global variables Secret files or information written Be careful about static variables Predictable Try to minimize use of other interfaces Make

as self-contained as possible Be explicit about external services required Document! Every class, method, interface, constructor, parameter, exception When states are kept, this should be very clearly documented Robust Able to deal with unexpected input Error Handling (see later)

Adaptable API can be extended, but never shortened Heavily used APIs likely will be extended Information Hiding Implementation API details should not affect

2. Resource Management Determine which side is responsible for Initialization Maintaining state Sharing and copying Cleaning up Various resources Memory Files Global variables Resource Management

Generally, free resources where they were allocated Return references or copies? Can have huge performance and ease of use impact Multi-threaded code makes this especially critical Reentrant: works regardless of number of simultaneous executions Avoid using anything (globals, static locals, other modifications) that others could also use Locks can be important

3. Error Handling Catch errors, dont ignore them Print message and fail is not always good Especially in APIs Need to allow programs to recover or save data Detect at low level, but handle at high level Generally, error should be handled by calling routine The callee can leave things in a nice state for recovery, though

Keep things usable in case the caller can recover Fail Fast Report as soon as an error occurs Sometimes even at compile time! Use of static types, generics Error Management Return values Should be in form the calling function can use Return as much useful information as possible Sentinel values only work if function cannot return all

possible values of that type Define pairs, or return another parameter to indicate errors Use error wrapper function if needed Consistent way of marking, reporting error status Encourages use But, can add complexity Exceptions Generally indicate a programming error Programming construct Set exception value (e.g. as return)

Other program operation when exception thrown Exceptions usually in global registry Include information about failure For repair and debugging Exceptions should generally be unchecked Automatically process globally, rather than require explicit checks over and over

Exceptions Only use in truly exceptional situations Never use as a control structure The modern GOTO Never use exceptions for expected return values e.g. Invalid file name passed to library is common, not an exception

Recently Viewed Presentations

  • Learning Services Fall Update 2015 Arkansas Department of

    Learning Services Fall Update 2015 Arkansas Department of

    Day 1-Essentials of Working With ELs; Day 2 Taking ELs to the Next Level ARKTESOL Conference, December 7, Hot Springs ADE staff providing training on ESOL Program Guidance Handbook, ELPA21, Title III Kelly Gallagher--Keynote Presentations by Arkansas ESOL Educators ESOL...
  • Ancient egypt jeopardy - Dunkirk High School

    Ancient egypt jeopardy - Dunkirk High School

    Vocabulary Question 1. Word Bank: Papyrus, Pyramid, Silt, Pharaohs, Afterlife, Mummies, Empire, Hieroglyphics, Tomb, Invaded. A room or a grave where a dead person is ...
  • Data and Knowledge Evolution - Hellas

    Data and Knowledge Evolution - Hellas

    Data and Knowledge Evolution Giorgos Flouris ... more mature Frame problems and provide inspiration towards a solution Protect from pitfalls Avoid "reinventing the wheel" Problems Representation languages and formalisms are different Assumptions regarding the underlying representation ...
  • What shape am I?  I have no flat

    What shape am I? I have no flat

    Title: PowerPoint Presentation Author: Claire Mackay Last modified by: Siminette Created Date: 7/9/2006 10:46:58 AM Document presentation format: On-screen Show (4:3)
  • Galaxies - Island universes

    Galaxies - Island universes

    From this, can solve for cluster mass, given the observed size and also the velocities of the member galaxies. Only strictly true if the cluster is "relaxed"; meaning the galaxies have moved through the cluster at least a couple of...
  • Interpretations of Hamlet - AP Literature

    Interpretations of Hamlet - AP Literature

    Through the layering of literary motifs and his profound exploration of themes, William Shakespeare's plays evoke an understanding of humanity that extends beyond his own time period of Renaissance England. In his play Hamlet, Shakespeare's subtle use of the motif...
  • Sedimentary Rocks - Weebly

    Sedimentary Rocks - Weebly

    Sedimentary Rocks Sedimentary Rocks are #1 Earth's crust was made of IGNEOUS rocks But 75% of the rocks on the Earth's crust are SEDIMENTARY! Why? Sedimentary rocks are created from the EROSION and DEPOSITION of other rocks. Formation of Sedimentary...
  • Hedges Breakfast Briefing: Property and Business 7 September

    Hedges Breakfast Briefing: Property and Business 7 September

    Occupiers' Liability Act 1984. Landowner still liable for injury in case of trespass onto private land. Criteria. Aware of danger. Reasonable grounds to believe trespasser is in vicinity of danger. Might reasonably be expected to offer protection against risk.