User Interface Principles in API Design
Elliotte Rusty Harold
elharo@metalab.unc.edu
http://www.cafeaulait.org/

Programmers Are People Too
Eat Like Humans
Sleep Like Humans
Mate Like Humans
Think Like Humans

User Interface Design is a Science
Based on hypothesis, observation and experiment
Well-proven, well-tested theories

Fundamental Principles
Consistency is next to godliness
Simpler is better
Visible complexity is bad
Smaller equals easier to use

Libraries vs. Applications
Applications are monolithic
Only other programmers on the same team use an application’s API
Libraries can make very limited assumptions about how, when, where, and why API will be invoked
Boundary is fuzzy

Remember the People
Why you need an API
Who uses the API
Who designs the API

What to put in an API
Write sample programs first
80/20 rule
Maximal vs. Minimal APIs
YAGNI
When in doubt, leave it out!
Why I’m a conservative

Dependencies
Platform version
Library dependencies
Built-in vs. 3rd party libraries

Data Encapsulation
Public vs. Published
Fields are private
Methods are mostly private
Methods are atomic
Constructors and destructors
Communicating with the user

Constraints
APIs must enforce domain validity
Preconditions
Postconditions
Class invariants
System invariants

Error Handling
Specify what happens on bad input as well as good
Important for security
No undefined behavior
Don’t silently swallow exceptions
Don’t warn the user

Naming Conventions
Review naming conventions
Use standard terminology
Do not abbreviate
Use domain specific vocabulary
Consistent terminology: always use the same word for the same idea
e.g. add vs. append
Do not use two words for one idea

Avoid Complexity
Prefer classes to interfaces
Prefer constructors to factory methods
Avoid excessive abstraction
You usually don’t need multiple implementations
Refactor to patterns; don’t start with them. Avoid pattern overload!

Inheritance
Prefer finality
(at least on methods)
Factories and interfaces
The proper use of protected

Plays well with others (Java):
Serializable
Cloneable(*)
Comparable
equals()
hashCode()
toString()
Exception handling
Thread safety

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

Testability
The API itself
Client code that uses the API
This is a secondary concern

Documentation
Specification
Quick Start
Tutorials
Example code
API Documentation
Per method checklist

Conformance Testing
Specifications
Test Suites
Implementation dependent behavior
Implementation dependent extensions

Maintenance
Planning for the future
Forwards compatibility
Backwards compatibility
Unexpected  limits
Deprecation
Breaking compatibility
Interfaces vs. classes

The Last Concern (Performance)
Speed
Size
Energy

Case Study: DOM vs. JDOM
Case Study: BoxLayout vs. GridBagLayout
Further Reading
Effective Java: Joshua Bloch
Effective C#: Bill Wagner
Framework Design Guidelines: Krzysztof Cwalina, Brad Abrams
Tog on Interface: Bruce Tognazzini
GUI Bloopers: Jeff Johnson