- Architecture Astrautics
- Inventing rather than extracting - Don't invent a libray, extract it out.
- Consistency
- Think like a wise man, speak in the language of common men
- Don't be syntactically clever.
- Warning Signs
- Frequent references to your own docs and source
- Don't invent syntax unless required and it pays off
- Brevity
- Warning Signs
- Copy-paste when writing your API
- Typing something irrelevant while grumbling
- Why cant I assume the obvious thing
- Long argument list, missing defaults
- Warning Signs
- Composibility
- Minimization of assumptions
- Warning Signs
- Classes with lots of state
- Deep Inheritance Hierarchy?
- Violating Law of Demeter
- Mocking in tests - Testable code is decoupled code
- Plain data
- No big hairy data structures as long as possible
- Reduce barries to reuse
-
Ex.
RawConfigParser.read(filename) # bad RawConfigParser.parse(string) # good
-
- Warning Signs
- Users immediately transform your output to another format
- Instantiating large objects just to pass to your function
- Rewriting language provided things
- Grooviness
- Avoid nonsense representations
- Fail shallowly (Looking at you javascript)
- RAII
- Warning Signs
- Represantable nonsense
- Invariants that aren't
- Lack of clear starting point
- Long complicated documentation
- Safety
- Throw an exception and not return a value
- Always separate unsafe APIs from safe APIs
- Warning Signs
- Docs say 'remember to' or 'make sure'
Last active
January 28, 2016 06:46
Build Poetic APIs
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment