程序的库设计

标签: Architecture API 设计 | 发表时间:2014-04-21 01:07 | 作者:四火
出处:http://www.raychase.net

程序的库设计 最近在Stack Exchange上面看到一个帖子,是问程序库设计的指导原则的,“ What guidelines should I follow while designing a library?”,有趣的是,很多人都在谈论面向设计,各路API设计,还有程序语言设计,唯独搜索“程序库设计”,无论中文还是英文,Google还是百度都找不到太多内容。但是我想,没有程序员会否认库设计的重要性吧,我想在这里结合这个帖子谈谈我的想法。

在这个帖子里面,votes最高的回答,提到了这样几类tips,我在下面简要叙述一下,其中基础的部分包括:

  • Pin Map,明确你期望库主要用来做什么,但不要把它定得太死,用户要可以比较方便地做出改变。
  • Working Library,一个工作的库,如果它连这点都达不到,一定要注明。没有人希望浪费时间在一个无法工作的程序库上面。
  • Basic Readme,清晰地描述库是用来做什么的,测试的情况等等。
  • Interfaces,接口必须清晰地定义,这可以帮助库的使用者。
  • Special Functions,特殊的功能,一定要注明,包括在readme文档中注明,以及在注释中注明。
  • Busy Waits,如果有一些场景需要使用busy wait(我不知道怎么翻译),其过程中可能会出现异常,使用interrupt或者其它妥善的方法来处理。
  • Comments,你做的任何的改变都要注释清楚,明确描述接口和其每个参数,方法是做什么的,又返回什么;如果有某个中间方法被调用到,就要注明。
  • Consistency,一致性,所有东西,包括注释。相关的方法要放在一个简单的代码文件里面,小但是逻辑一致。

其中的高级部分又包括Detailed Readme,Directory Structure,Licensing和Version Control。

这些都是需要注意的内容,并且大部分对于程序的库设计来说是基础要求,但是这些从重要性来说,并没有说到点上。《C++沉思录》里面有这样一句话:“库设计就是语言设计,语言设计就是库设计”,二者从先定义问题域到后解决问题的思路是类似的。我觉得比较重要的需要考虑的事情包括:

考虑库的目标用户。这听起来扯得有点泛,但实际上这是确切的问题,这是开源库还是你只是在小组内部使用的库,或者是公司内部使用的?用户的能力和需求是不一样的,要求当然不同。

要解决的核心问题。这是上文中Pin Map的一部分,不要重复发明轮子,那么每一个新库都有其存在的价值,这个问题既要通用又要具体,“通用”指的是库总有一个普适性,解决的实际问题对于不同的用户来说是不一样的;而“具体”是指库解决的问题对于程序员来说是非常清晰和直接的。例如设计一个库,根据某种规则把不同的数据类型(XML,BSON或者某种基于行的文本等等)都转换成JSON。

统一的编程风格。很多库都有自己精心设计的一套DSL, 比如链式调用等等几种方式,当然,这也和使用的语言有关系。定义一种用起来舒服的编程风格对于程序库的推广是很有好处的。这也是一致性的一个体现。

内聚的调用入口。这和面向对象的“最少知识原则”有类似的地方,把那些不该暴露出去的库内部实现信息隐藏起来,在很多情况下,程序库不得不暴露和要求用户了解一些知识的时候,比如:

MappingConfig config = new MappingConfig();
config.put(MappingConfigConstants.ENCODE, "UTF-8");
FileBuilder fileBuilder = new StandardFileBuilder(mapping);
InputStream stream = fileBuilder.build().getInputStream();
DataTransformer<XMLNode> transformer = new XMLDataTransformer(...);
...
transformer.transform(stream);

这里引入了太多的概念,MappingConfig、FileBuilder、DataTransformer等等,整个过程大致是构造了一个数据源,还有一个数据转换器,然后这个数据转换器接受这个数据源来转换出最后结果的过程。那么:

这些象征着概念的接口和类最好以某种易于理解的形式组织起来,比如放在同一层比较浅的包里面,便于寻找;

也可以建立一个facade类,提供几种常用的组合,避免这些繁琐的对象构建和概念理解,例如:

XXFacade.buildCommonXMLTransformer();

向后兼容。当然,这一点也可以归纳到前文提到的一致性里面去。 我曾经拿JDKHashTable举了一个例子,它的containsValue和contains方法其实是一样的,造成这种情况的一个原因就是为了保持向后兼容。

依赖管理。依赖管理很多情况下是一个脏活累活,但是却不得不考虑到。通常来说,任何一个库考虑自己的依赖库时都必须慎重,尤其是面对依赖的库需要升级的时候。如果依赖的库出了问题,自己设计的程序库也可能因此连累。

完善的测试用例。通常来说,程序库都配套有单元测试保证,无论是什么语言写的。

健全的文档组织。通常包括教程(tutorial)、开发者文档(developer guide)和接口API文档(API doc)。前者是帮助上手和建议使用的,中间的这个具备详尽的特性介绍,后者则是传统的API参考使用文档。

 

文章未经特殊标明皆为本人原创,未经许可不得用于任何商业用途,转载请保持完整性并注明来源链接 《四火的唠叨》

分享到:
你可能也喜欢:

相关 [程序 设计] 推荐:

程序的库设计

- - 四火的唠叨
最近在Stack Exchange上面看到一个帖子,是问程序库设计的指导原则的,“ What guidelines should I follow while designing a library?”,有趣的是,很多人都在谈论面向设计,各路API设计,还有程序语言设计,唯独搜索“程序库设计”,无论中文还是英文,Google还是百度都找不到太多内容.

Android 程序框架设计

- - 互联网的那点事
每个模式都描述了一个在我们的环境中不断出现的问题,然后描述了该问题的解决方案的核心. 通过这种方式,你可以无数次地使用那些已有的解决方案,无需在重复相同的工作. 设计模式是在某种特别的情况下,针对某种问题的某种典型、通用的解决方法. 我们是需要适当了解并学习一些设计模式,在程序开发过程中,总是会涉及到一些框架设计,模块设计之类的东西,如果能很好理解并运行设计模式,你所设计的模块或框架将会要稳定得多,因为这些设计模式它们都是通用的解决方案,是经过实践经验了的.

简析 IOS 程序图标的设计

- 星空无语 - 所有文章 - UCD大社区
程序图标主要作用是为了使该程序更加具象及更容易理解,除了上述的作用外,有更好视觉效果的图标可以提高产品的整体体验和品牌,可引起用户的关注和下载,激发起用户点击的欲望. 在有限的空间里表达出相对应的信息,在IOS 程序图标设计中,直观是第一个解决的问题,不应该出现大多繁琐的修饰,当然还要有很好的视觉表现力,使用户可以更容易理解此应用的实际作用,更轻松地辨识此应用.

最隐晦的程序设计指引

- Sirius - Dev in Nightmare
    俗话说,程序员半年不学新东西,就变奥特曼(out man,过时之人)了. IT行业可以说是变化最快的行业,每年都有大量的新概念、新术语、新技术被创造出来,在多数人还在一头雾水时,“更好的”替代品又被创造出来.     想当年静态类型系统是王道,谁要是搞点运行时动态绑定、用点VB什么的,经常会被鄙视.

高性能LAMP程序设计

- Kevin - 超群.com的博客
周六分享的PPT,一些比较common的大杂烩,看不到slides的同学在这里查看.

炮轰老谭的<<C程序设计>>

- 世博 - 博客园-首页原创精华区
  本人不学无术, 生财无方, 下作无品, 见园里一小女初学C#的文章都能上评论头条, 实在眼红得不知所谓, 于是写下此随笔, 绝不敢效仿hax, 只为吸引眼球而已, 读者诸君就当看小丑跳梁好了.. #188楼2011-09-27 03:27 | 陈梓瀚(vczh)      . 为了免去翻阅旧评论的痛苦,“62楼”不辞辛苦复制一遍winter-cn给的地址,你们一定要看啊…….

并发程序设计详解

- - 企业架构 - ITeye博客
Java性能优化系列之三--并发程序设计详解. 线程安全 设计模式 多线程 并行计算 并发.   (1)、Future-Callable模式:FutureTask类实现了Runnable接口,可以作为单独的线程运行,其Run方法中通过Sync内部类调用Callable接口,并维护Callable接口的返回值.

【测试调查】你是程序员还是程序设计师?

- - 外刊IT评论
二十年前,顶尖的程序员能将一个完整的应用放到一个64KB大小的 .COM文件里. 这是他们对可怜的因特尔80386电脑在编程上进行的最大挖掘. 这是因为,二十年前,电脑昂贵而程序员便宜. 那种理念已经不再有人欣赏,因为如今的市场形势发生了完全的颠覆. 如今,计算机便宜而程序员昂贵. 这是一个“程序员为先”的年代,不再需要考虑计算机的能力和限制,程序员的因素放到了第一位.

经典网页设计:精心设计的 iPhone 和 Android 应用程序网站

- - 博客园_梦想天空
  这篇文章和大家分享一组精心设计的 iPhone 和 Android 应用程序网站. 在一个应用程序的网站,从醒目的图像到有趣的标题和产品信息等等,你可以找到很多的灵感. 今天的文章中收集的这些设计精美的应用程序网站为我们的网站设计和制作提供了各种各样的思路,都是真正优秀和杰出的设计,值得借鉴和学习.

硅谷“老黄忠”程序员:Google+设计者上榜

- beralee - cnBeta.COM
美国科技博客BusinessInsider今天撰文分析了目前依旧位居一线的老计算机程序员,这其中包括了万维网之父Tim Berners-Lee等知名科技界人物,谷歌最新社交网络Google+圈子的用户界面设计者Andy Hertzfeld也在该榜单中.