- 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
-
-
Save nerandell/8dbf828947c7f21fcc3c to your computer and use it in GitHub Desktop.
Build Poetic APIs
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment