좋은 API 설계하기

들어가며

이 글은 2007년에 나온 구글 테크톡 How To Design A Good API and Why it Matters에 대한 내용정리 글이다.

좋은 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 evolve
• Appropriate to audience

API Design

요구사항 수집

• Don`t just accept solutions, diig deeper to find the true underlying problem.
• Usecases are essential
• Keep the spec short
• Code early and often

Start with Short Spec - 1 Page is Ideal

• At this stage agility trumps completeness
• Bounce spec off as many people as possible
• keep the spec short, it's easy to modify
• Flesh it out as you gain confidence

Write to Your API Early and Often

• Start before you've implemented the API
  - Saves you doing implementation you'll throw away
• Start before you've even specified it properly
  • Saves you from writing specs you'll throw away
• Continue writing to API as you flesh it out
• Code lives on as examples, unit tests

Writing to SPI is Even More Important

SPI : Service Provider Interface
간단히 설명하자면 암호화 API가 있을때 암호화 알고리즘 구현체를 API 사용자가 교체하며 사용할 수 있도록 만드는 방식

• Write multiple plugins before release

Maintain Realistic Expectations

• Most API designs are over-constrained
• Expect to make mistakes

API Should Do One Thing and Do it Well

• Functionality should be easy to explain
  - If it's hard to name, that's generally a bad sign

API Should Be As Small As Possible But No Smaller

• API should satisfy its requirements
• When In doubt leave it out
• Conceptual weight more important than bulk
• Look for a good power-to-weight ratio

Implementation Should Not Impact API

• Implementation details
  - Confuse uesrs
  • Inhibit freedom to change implementation
• Be aware of what is an implementation detail
• Don't let implementation details "leak" into API

Minimize Accessibility of Everything

• Make classes, members as private as possible
• Public classes should have no public fields
• Maximizes information hiding
• Minimizes coupling
  - Allows modules to be, understood, used, tested, debugged, and optimized independently

Names Matter-API is a Little Language

• Names Should Be Largely Self-Explanatory
• Be consistent
  - Same word means same thing throughout API
• Be regular-strive for symmetry
• If you get it right, code reads like prose(산문)

Consider Performance Consquences of API Design Decisions

성급한 최적화는 좋지 않지만 이것이 성능을 무시하란 의미는 아니다.

• Bad decisions can limit performance
• Do not warp API to gain performance

API Must Coexist Peacefully with Platform

• Do what is customary(관례적인)
• Take advantage of API-friendly features
• Know and avoid API traps and pitfalls(함정)
• Dont't Transliterate(음차: 발음대로 적는 것) APIs
  - C++걸 Java로 그대로 옮기지 마라

Minimize Mutability

• Classes should be immutable unless there's a good reason to do otherwise
• If mutable, keep state-space small, well-defined
  - Make clear when it's legal to call which method

Subclass Only Where It Makes Sense

• Subclassing implies substitutability (Liskov)
  - Subclass only when is-a relationship exists
• Public classes should not subclass other public classes for ease of implementation

Design and Document for Inheritance or Else Prohibit it

• Inheritance violates encapsulation
• If you allow subclassing, document self-use
• Conservative(보수적) policy: all concerte classes final

Don't Make the Client Do Anything the Module Could Do

• Reduce need for boilerplate code
  - 굳이 사용자가 이것저것 반복호출하거나 준비하게 하지 마라.

Don't Viloate the Principle of Least Astonishment

• Users of API should not be surprised by behavior
  - It's worth extra implementation effort
  • It's even worth reduced performance

Fail Fast-Report Errors as Soon as Possible After They Occur

• Compile time is best - static typing, generics
• At runtime, first bad method invocation is best

Provide Programmatic Access to All Data Available in String Form

• Otherwise, clients will parse strings
  - Painful for clients

Overload With Care

• Avoid ambiguous overloadings
  - Multiple overloadings applicable to same actuals
  - Conservative: no two with same number of args
• Just because you can doesn't mean you should
• If you must provide ambiguous overloadings, ensure same behavior for same arguments

Use Appropriate Parameter and Return Types

• Favor interface types over classes for input
• Use most specific possible input parameter type
• Don't use string if a better type exists
  - Strings are cumbersome(다루기 어렵다), error-prone, and slow
• Don't use floating point for monetary values
• Use double (64 bits) rather than float (32 bits)
  - Precision loss is real, performance loss negligible(무시가능한)

Use Consistent Parameter Ordering Across Methods

• Especially important if parameter types identical

Avoid Long Parameter Lists

• Three or fewer parameters is ideal
• Long lists of identically typed params harmfull
• Techniques for shortening parameter lists
  - Break up method
  • Create helper class to hold parameters

Avoid Return Values that Demand Exceptional Processing

• Return zero-length array or empty collection, not null

후기

테크톡 1시간 제한 두지 마라