API设计及命名技巧

• 参考:

  • 好文: API 設計 與 命名 技巧

  • 程序命名的一些提示

    • [8g]被误解的匈牙利命名法

  • Software Engineering Tips

    • API Design Tips

    • Naming Tips

概述

API 如何設計? 該怎麼命名? 一直都是很頭痛的問題~

API 的設計, 一個錯誤可能要40年才有機會修正, 詳細可見: 一個關於Ken Thompson的小故事

API 设计技巧

• 命名是一切！ Naming is everything
• 关键是减少复杂 The point is to reduce complexity
• 回避无谓的边界效应 Eschew unnecessary side effects
• 使用控制倒转法保持必要的边界效应 Use Inversion of Control (IoC) to handle necessary side effects
• 对大块IoC使用事务 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
  • Erlang 用到了内核
  • Unix 用成了安静的死亡
  • 我们呢? 应该配合 Unite Test 将一切非设计的意外,都丢到异常中!
• 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

命名技巧

• 方法,类和值 Methods, Classes and Variables

  • 不要命名方法类似 "ProcessData()"废话! 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
  • 避免类名用"Manager"结尾 Avoid class names that end with "Manager"
  • 用单数名称命名枚举值 Use singular names for enumerations
    • 因为最终你只是使用其中的一个
  • 匈牙利命名法应该用作含义而不是类型 Hungarian notation should encode meaning, not type

    • [8g]被误解的匈牙利命名法

  • 不要藏在你的命名之后 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

• 宁要命名空间,也不要类似"nsStupidClassPrefix" Prefer namespaces instead of "nsStupidClassPrefix"
  • OOP 时代我们的偷懒方法!

• 使用普通的namespace而不是使用公司名 Extend a generic namespace, don't create MyCompanyName.Widgets

* 数据库 Databases

• 对表使用复数命名 Use pluralized names for tables
• 使用aux_或mate_命名源数据/内务表 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

反馈

创建 by -- ZoomQuiet [2010-01-11 03:48:04]