CSCE 431 Lecture 15

« previous | Tuesday, March 18, 2014 | next »

Begin Exam 2 content

Why API Design Matters

Every programmer is an API designer;

Shared code is considered an API, even among a small number of developers.

Characteristics of a Good API

• 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.

"Eat your own dog food"

Use your own API!

Write to it early and often (even if not yet implemented or even fully specified)

The code you write will live on as unit tests and example uses (documentation)

Expect the API to evolve.

"Rule of threes"

• Write first client before release, will not support another.
• Write a second client before release, will support more with difficulty.
• Write three clients before release, will work fine.

Broad Issues

• Interface (classes, methods, parameters, names)
• Resource Management
• Error Handling (what errors are caught and what is done to handle them?)
• Information Hiding

Interface

• Simple: keep it simple, stupid! Functions should do one thing and do it well.
• General: implementation can change, API cannot.
• Regular: Use same conventions across all similar or related functions (units, parameter ordering like source/dest)
• Predictable: things do what they say; understandable without referring to documentation
• Robust: Handle unexpected input
• Adaptable

Resource Management

Lifecycle usually begins and ends in the same place (except perhaps in a factory)

Return references or copies?

Error Handling

Catch errors, do not ignore them.

"Print message and fail" is not always good.

Detect at low level, but handle at high level

• handle error in caller
• callee should leave things in a "nice" state and provide useful information about the error. (caller might be able to recover from the error)