好文: API 設計 與 命名 技巧

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

相關網頁

• Designing Qt-Style C++ APIs - Six Characteristics of Good APIs

作者: Tsung

對新奇的事物都很有興趣, 喜歡簡單的東西, 過簡單的生活. 檢視「Tsung」的全部文章