Skip to content

Instantly share code, notes, and snippets.

@nrb

nrb/gist:7999216

Last active December 31, 2015 14:19
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save nrb/7999216 to your computer and use it in GitHub Desktop.
Save nrb/7999216 to your computer and use it in GitHub Desktop.
Download ZIP
My PyCon 2014 talk proposal, for sharing.
Raw
gistfile1.md

*** what about long term vs short term use? ***** Perceived Differences Between Devs and Designers

  • Developers don't have to worry about design
    • Or, only 'hybrids' have to.
  • Design is only the front-end part of the application
    • Maaaaybe architecture design ("Big Design Up Front"/BDUF)

Both of These are Wrong

  • 'Design is how it works' - Steve Jobs
    • Jobs is pointing out that design is not an afterthought; it's the crafting of the project
  • Design happens as you build your software.
    • Every decision you make in the course of writing the software is design.

Design of APIs

  • Your API is a Contract
    • You can't just wrap something with the same method names and call it good
      • Wrapping SQLAlchemy objects in a Django ORM call scheme still returns SQLAlchemy objects, which breaks the Djano-ORM contract.
  • Does it to conform to user expectations?
    • In Ruby, methods with 0 arguments usually aren't called with parentheses; theory is user shouldn't care if a value is computed or a simple attribute.
    • In Python, methods with 0 arguments have to have parentheses (unless a property); theory is the user should know computation is happening so they are prepared for potentional speed hits.
  • Names
    • Classes, Methods, Variables
  • Arguments
    • Argument names, keyword arguments, order, data types
    • Passing in a whole object, vs individual attributes
  • Return values
    • Return None ever?
    • Allow chainable methods? (e.g. returning self)
  • Exceptions
    • Exceptions ARE a kind of return value
  • File/Import Stucture
    • I'd argue this part of your API. Compare python/ruby imports to Java nesting.
    • Is it navigable?
    • Are things monkey patched and hard to find?
    • Is it easy for tools (ctags, IDEs) to navigate?
  • Documentation
    • How easy are your docs to navigate?
    • Do they cover the things users want to do?
    • Is a design defense written? Pyramid and Flask are great examples.
      • These can help users more fully understand
  • Deprecation policies
    • How many versions will you give users to switch?
      • 0 is a bad number.

How Does Testing Help Design?

  • Is your design hard to test?
    • It's probably hard to use, then.
  • Does it have tests?
    • If you haven't used the API yourself, how do you know it's good?
  • Are you using a lot of fakes/mocks?
    • You may have too many dependencies
  • Your API Makes Me Fat: http://seriouspony.com/blog/2013/7/24/your-app-makes-me-fat
    • You should do as much as you can to cater to your users, vs. making things easy on you, but harder on your users.
    • Let the user work on their problem, don't BECOME their problem.

Be Human

  • Reasonable names, reasonable errors
  • Empathy
  • Consistency
  • 80/20 rule
  • Allow an escape hatch
    • What if a user wants to do something you didn't think about? Exposing internals can help
  • Flexibility
    • Lots of stdlib modules in Python take 'file-like' objects, not just files.

Who is Your Audience

  • Targeting for Skill Level
    • Beginner, Intermediate, Advanced
  • Are you targetting it for others?
    • Only yourself in the future? (a private project)
    • Your coworkers?
    • The 'public,' if open source/free software
  • Remember, readability is a function of your audience.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment