My PyCon 2014 talk proposal, for sharing.
*** what about long term vs short term use? *****
Perceived Differences Between Devs and Designers
Both of These are Wrong
- 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)
Design of APIs
- '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.
How Does Testing Help Design?
- 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.
- Classes, Methods, Variables
- 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 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?
- 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?
- 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.
Who is Your Audience
- Reasonable names, reasonable errors
- 80/20 rule
- Allow an escape hatch
- What if a user wants to do something you didn't think about? Exposing internals can help
- Lots of stdlib modules in Python take 'file-like' objects, not just files.
- 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.