API 如何設計? 該怎麼命名? 一直都是很頭痛的問題~
API 的設計, 一個錯誤可能要40年才有機會修正, 詳細可見: 一個關於Ken Thompson的小故事.
下述文章都取自此站: Software Engineering Tips
此站還有蠻多 Tips 和 教學文件可以參考.
API Design Tips
下述轉載自: API Design Tips
- Naming is everything
- The point is to reduce complexity
- Eschew unnecessary side effects
- Use Inversion of Control (IoC) to handle necessary side effects
- Use events for the bulk of your IoC
- Use Interfaces everywhere
- Use Interfaces that cover everything you need, but not more and not less
- Don't make your own gravity
- return all of your results from the function call
- The consumer isn't Sherlock Holmes
- Distinguish types of failures
- Support optional parameters
- true and false are lousy arguments
- Use consistent calling conventions
- Nouns should be value types, verbs should be static functions. Or: Don't Make "Manager" Classes
- Fail early
- Don't be the weak link in the chain
- One API at a time
- One level of abstraction at a time
- Expose wrappers for value types, but accept strings anyway
- Always return the richest type
- Implement IClonable, INotifyPropertyChanged, ISerializable and other handy interfaces for your value types
- Provide flexibility and isolation for configuration
- Keep your knickers to yourself
- Only throw exceptions for the exceptional
- Document the exceptions you throw
- Document how to do what your consumers tend to do
- Flag deviations from the norm
- Consider shipping your unit tests
- Don't ship an API you haven't used in a useful, working program
Naming Tips
下述轉載自: Naming Tips
- Methods, Classes and Variables
- Do not name methods "ProcessData()"
- Use naming to help you design the program
- If it's general, it better be generalized
- Avoid discussing hard work
- Avoid class names that end with "Manager"
- Use singular names for enumerations
- Hungarian notation should encode meaning, not type
- Don't hide behind your names
- Don't forget to have a vowel movement
- Consistency, Consistency, Consistency
- Don't be afraid to rename
- Frameworks & Libraries
- Prefer namespaces instead of "nsStupidClassPrefix"
- Extend a generic namespace, don't create MyCompanyName.Widgets
- Databases
- Use pluralized names for tables
- Use aux_ and meta_ for tables that contain derived data or housekeeping junk
- Name surrogate primary keys after the table
- Use a postfix to show the kind of key
- Things
- Name physical things what they are, not what they're doing
- Name logical things after what they're doing, not what they are
- Avoid the "Category" problem