##language:zh #pragma section-numbers off ##含有章节索引导航的 ZPyUG 文章通用模板 <> ## 默许导航,请保留 <> = API设计及命名技巧 = * 参考: * [[http://plog.longwin.com.tw/document-ebook/2009/12/29/paper-api-design-naming-tips-2009|好文: API 設計 與 命名 技巧 | Tsung's Blog]] * [[http://coolshell.cn/?p=1990|程序命名的一些提示 | 酷壳 - CoolShell.cn]] * [[http://www.laihj.net/2010/01/hungarian%EF%BC%8Dnotation/|[8g]被误解的匈牙利命名法 | 右舷]] * [[http://sites.google.com/site/yacoset/Home|Software Engineering Tips]] * [[http://sites.google.com/site/yacoset/Home/api-design-tips|API Design Tips]] * [[http://sites.google.com/site/yacoset/Home/naming-tips|Naming Tips]] ##startInc == 概述 == API 如何設計? 該怎麼命名? 一直都是很頭痛的問題~ API 的設計, 一個錯誤可能要40年才有機會修正, 詳細可見: [[http://kevinwatt.net/blog/?p=104|一個關於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 * [[http://www.laihj.net/2010/01/hungarian%EF%BC%8Dnotation/|[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 ##endInc == 反馈 == 创建 by -- ZoomQuiet [<>] ||<^><>||<^> ''[[/PageCommentData|e评注]]''||