一个软件项目,一般需要交付两类文档。一类文档是面向开发者的,另一类文档是面向最终用户的。这两类文档,由于面向用户的不同,无论是内容还是形式,都有巨大的差异。今天我们先来聊聊面向开发者的文档。下一讲中,我们再接着聊面向最终用户的文档。
区分外部接口和内部实现
为了便于维护和协作,一个软件通常被划分为几个不同的部分。比如我们通常使用的 MVC 架构,把软件分为模型(Model)、视图(View)和控制器(Controller)三个部分。这样做,可以降低复杂度,让程序结构更加直观。同时,这种架构也很容易对程序进行修改和扩展,并且可以重复利用基础的功能。
不同功能的分离,让程序员之间产生了分工,专业人员可以更聚焦于个人的专长领域。这是一个多赢的局面,也能让软件的质量得到提升。
既然有分工,就要有协作。MVC 架构把软件拆分为三块,是分工;而 MVC 模块之间的调用关系,就是协作。
一个好的软件设计,要区分外部接口和内部实现。外部接口,就是协作的界面,要简单规矩;内部实现,可以是千变万化的复杂小世界。
这种区分无处不在,即使是最普通的 API。比如我们常用的 InputStream,一旦我们获得这个对象实例,就可以调用它的 read() 方法。 我们不用去关心,它的底层实现是一个文件,一段内存,还是一个远程连接。InputStream 的接口定义只有十个方法,短短的 500 多行代码。