![Page 1: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/1.jpg)
User Interface Principles in API Design
Elliotte Rusty Harold
http://www.cafeaulait.org/
![Page 2: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/2.jpg)
““API usability is the intersection API usability is the intersection of user-centered design and of user-centered design and excellent coding practices”excellent coding practices”
--David Koelle & Geertjan Wielenga
![Page 3: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/3.jpg)
Programmers Are People TooProgrammers Are People Too
Eat Like HumansSleep Like HumansMate Like HumansThink Like Humans
![Page 4: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/4.jpg)
User Interface Design is a User Interface Design is a ScienceScienceBased on hypothesis, observation
and experimentWell-proven, well-tested theories
![Page 5: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/5.jpg)
Fundamental PrinciplesFundamental Principles
Consistency is next to godlinessSimpler is betterVisible complexity is badSmaller equals easier to use
![Page 6: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/6.jpg)
Libraries vs. ApplicationsLibraries vs. Applications
Applications are monolithicOnly other programmers on the
same team use an application’s APILibraries can make very limited
assumptions about how, when, where, and why API will be invoked
Boundary is fuzzy
![Page 7: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/7.jpg)
Remember the PeopleRemember the People
Why you need an APIWho uses the APIWho designs the API
![Page 8: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/8.jpg)
Be User FocusedBe User Focused
Ask what the user wants to do with your API
Do not ask what the internal data structures and algorithms look like
High level API is better than lower level--Reduce the number of method calls needed to accomplish the task
Design from the outside in Start with the end in mind
![Page 9: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/9.jpg)
What to put in an APIWhat to put in an API
Write sample programs first; Sample-first programming
80/20 rule
Maximal vs. Minimal APIs
YAGNI
When in doubt, leave it out!
Why I’m a conservative
![Page 10: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/10.jpg)
DependenciesDependencies
Platform versionLibrary dependenciesBuilt-in vs. 3rd party libraries
![Page 11: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/11.jpg)
Data EncapsulationData Encapsulation
Public vs. Published Fields are private Methods are mostly private Methods are atomic Constructors and destructors Communicating with the user
![Page 12: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/12.jpg)
ConstraintsConstraints
APIs must enforce domain validity
PreconditionsPostconditionsClass invariantsSystem invariantsConstruct complete objects only (Builder pattern)
![Page 13: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/13.jpg)
Error HandlingError Handling
Specify what happens on bad input as well as good
Important for securityNo undefined behaviorDon’t silently swallow exceptionsError messages should be verbose
but clearDon’t warn the user
![Page 14: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/14.jpg)
Naming ConventionsNaming Conventions
Review naming conventionsUse standard terminologyDo not abbreviateUse domain specific vocabularyConsistent terminology: always use
the same word for the same idea– e.g. add vs. append
Do not use two words for one idea
![Page 15: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/15.jpg)
Avoid ComplexityAvoid Complexity
Prefer classes to interfacesPrefer constructors to factory
methodsAvoid excessive abstractionYou usually don’t need multiple
implementationsRefactor to patterns; don’t start with
them. Avoid pattern overload!
![Page 16: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/16.jpg)
InheritanceInheritance
Prefer finality– (at least on methods)
Factories and interfacesThe proper use of protected
![Page 17: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/17.jpg)
Plays well with others (Java):Plays well with others (Java):
Serializable Cloneable(*) Comparable equals() hashCode() toString() Exception handling Thread safety
![Page 18: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/18.jpg)
Plays well with others (.NET):Plays well with others (.NET):
Equals() / GetHashCode() ToString() IEquatable<T> / IComparable<T> “Collection” suffix for IEnumerable classes Icloneable* Override ==, etc. for value types (only) No pointer arguments to public methods Don’t throw exceptions from overloaded
operators and implicit casts
![Page 19: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/19.jpg)
TestabilityTestability
The API itselfClient code that uses the APIThis is a secondary concern
![Page 20: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/20.jpg)
DocumentationDocumentation
SpecificationQuick StartTutorialsExample codeAPI DocumentationPer method checklist
![Page 21: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/21.jpg)
Conformance TestingConformance Testing
SpecificationsTest SuitesImplementation dependent behaviorImplementation dependent
extensions
![Page 22: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/22.jpg)
MaintenanceMaintenance
Planning for the futureForwards compatibilityBackwards compatibilityUnexpected limitsDeprecationBreaking compatibilityInterfaces vs. classes
![Page 23: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/23.jpg)
The Last Concern (Performance)The Last Concern (Performance)
SpeedSizeEnergy
![Page 24: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/24.jpg)
Case Study: JMidi vs. JFugueCase Study: JMidi vs. JFugue
![Page 25: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/25.jpg)
JMidi: Play Middle-C JMidi: Play Middle-C
Sequencer sequencer = MidiSystem.getSequencer();Sequence sequence = sequencer.getSequence();Track track = sequence.createTrack();ShortMessage onMessage = new ShortMessage();onMessage.setMessage(ShortMessage.NOTE_ON, 0, 60, 128);MidiEvent noteOnEvent = new MidiEvent(onMessage, 0);track.add(noteOnEvent);ShortMessage offMessage = new ShortMessage();offMessage.setMessage(ShortMessage.NOTE_OFF, 0, 60, 128);MidiEvent noteOffEvent = new MidiEvent(offMessage, 200);track.add(noteOffEvent);sequencer.start();try { Thread.sleep(track.ticks());} catch (InterruptedException e) { Thread.currentThread().interrupt();} // courtesy of David Koelle
![Page 26: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/26.jpg)
JMidi: Play Middle CJMidi: Play Middle C
Player player = new Player();
player.play("C");
// Play first 2 measures (and a bit) of “Für Elise”
player.play("E6s D#6s | E6s D#6s E6s B5s D6s C6s | A5i.");
// courtesy David Koelle
![Page 27: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/27.jpg)
Lessons LearnedLessons Learned
Domain Specific Language– Takes advantage of domain specific knowledge– Easier to write; easier to read– Java is not the right notation for all use cases
(nor is XML, nor Ruby, nor JSON, nor SQL, nor…)
Focus on what the client wants to do; not how the software does it
Avoid Abstract Factory; don’t catch “patternitis”
![Page 28: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/28.jpg)
Case Study: BoxLayout vs. Case Study: BoxLayout vs. GridBagLayoutGridBagLayout
![Page 29: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/29.jpg)
Gridbag CalculatorGridbag Calculator
![Page 30: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/30.jpg)
BoxLayout CalculatorBoxLayout Calculator
![Page 31: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/31.jpg)
Lessons LearnedLessons Learned
Follow naming conventionsFocus on what the user wants to do;
not the internal data model and algorithms
![Page 32: User Interface Principles in API Design Elliotte Rusty Harold elharo@metalab.unc.edu](https://reader036.vdocuments.us/reader036/viewer/2022062515/56649c725503460f949246e8/html5/thumbnails/32.jpg)
Further ReadingFurther Reading
Effective Java: Joshua BlochEffective C#: Bill WagnerFramework Design Guidelines:
Krzysztof Cwalina, Brad AbramsTog on Interface: Bruce TognazziniGUI Bloopers: Jeff Johnson