In API design I’ve always found this keynote very helpful:
How to Design a Good API and Why it Matters – by Joshua Bloch
Here’s an excerpt, I’d recommend reading the whole thing / watching the video.
II. General Principles
- API Should Do One Thing and Do it Well
- API Should Be As Small As Possible But No Smaller
- Implementation Should Not Impact API
- Minimize Accessibility of Everything
- Names Matter–API is a Little Language
- Documentation Matters
- Document Religiously
- Consider Performance Consequences of API Design Decisions
- Effects of API Design Decisions on Performance are Real and Permanent
- API Must Coexist Peacefully with Platform
III. Class Design
- Minimize Mutability
- Subclass Only Where it Makes Sense
- Design and Document for Inheritance or Else Prohibit it
IV. Method Design
- Don’t Make the Client Do Anything the Module Could Do
- Don’t Violate the Principle of Least Astonishment
- Fail Fast – Report Errors as Soon as Possible After They Occur
- Provide Programmatic Access to All Data Available in String Form
- Overload With Care
- Use Appropriate Parameter and Return Types
- Use Consistent Parameter Ordering Across Methods
- Avoid Long Parameter Lists
- Avoid Return Values that Demand Exceptional Processing