Build Poetic APIs

BuildPoeticAPIs.md

Build Poetic APIs

Steps to follow

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

Further reading

• Slides
• Video