好文: 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

相關網頁


關於 Tsung

對新奇的事物都很有興趣, 喜歡簡單的東西, 過簡單的生活.
本篇發表於 Document-Ebook。將永久鏈結加入書籤。

好文: API 設計 與 命名 技巧 有 2 則回應

發表迴響

這個網站採用 Akismet 服務減少垃圾留言。進一步瞭解 Akismet 如何處理網站訪客的留言資料