从一道作业题谈一点开源规范

11 Jul, 2012

在 William Stallings 的操作系统教材《操作系统——精髓与设计原理》中有一个编程实验题,开发一个简单的 shell 程序,在题目中,要求实现一个基本的 shell 功能,然后是下面的一些要求:

  1. 设计一个简单的命令行 shell,满足上面的要求并且在指定的 UNIX 平台下执行。
  2. 写一个关于如何使用 shell 的简单用户手册,用户手册应该包含足够的细节以方便 UNIX 初学者使用。例如,你应该解释 I/O 重定向、程序环境和后台程序执行。用户手册必须命名为 readme,必须是一个标准文本编辑器可以打开的简单文本文档。举一个描述的类型和深度的例子,你应该看一下 csh 和 tcsh 的在线帮助(man csh,man tcsh)。这两个 shell 显然比你的 shell 有更多的功能,你的用户手册没必要做的那么大。不要包括编译指示——文件列表和源码,我们可以从你提交的其它文件中找出来。这应该是操作手册而非程序员手册。
  3. 源码必须有很详细的注释,并且要有很好的组织结构以方便别人阅读和维护。结构和注释好的程序更加易于理解,并且可以保证批改你作业的人不用很费劲地去读你的代码。
  4. 提交内容为源代码文件,包括文件、makefile(全部小写)和 readme(全部小写)文件。批改者会重新编译源代码,如果编译不通过将没有办法打分。

先不论题目本身的难度,就这些要求来说,已经是非常严格了,比如必须包括一个用户手册,对于用户手册,应该包含足够的细节,大部分用户不是程序员,他们不想为了寻找某个功能的使用方法而去阅读源代码,他们更不会去读源代码以寻找更多你的手册中没有写出来的功能,他们唯一愿意做的就是 remove,然后搜索其它。如果开源从根本上的利益是获得成就感,那么你真的需要去重视你程序的使用指南,开源可不是扔一堆源代码出去就完了。

在 UNIX 系统下,对用户手册有比较严格的要求,比如必须是简单的文本文件,只要有文本编辑器就可以打开阅读,同时也可以使用 man 命令查看,请不要使用极具平台特色的文件,比如 doc 什么的。文本文件也因为简单而有一些弊端,比如在排版上很难,解决方法有很多,比如使用标记语言,比如 Markdown。对于复杂拥有庞大主题的文档,在线手册也很有必要,比如你可以使用 Github 的 Page 或者 Wiki,在线托管文档的 Read the Docs,在 Python 下,可以使用 Sphinx 制作排版生成文档。

对于开源软件,也要照顾一类特殊用户,他们想要通过你的源代码学习编程,或者想 hack 一下你的源代码,让它变得更好(也有可能变的更坏),所以你的源代码须要清晰简洁,注释适当,组织结构要好,以方便他人的阅读与维护,没有协作的开源是很难生存下去的开源,这就是 Github 会非常火的原因。对于 UNIX 或者类 UNIX 下的开源软件,只需要提供源代码文件,编译指示(通常一个 makefile 文件)就可以了,不用提供已经编译好的二进制文件,因为平台特性,可能会出现兼容问题,不过使用包管理也不错,在这方面不是很熟,所以也就不扯下去了。

开源这个词似乎还是在国外比较流行,从这个教材的这套题就可以看出,当然也免不了因为 Stallings 先生也是从当年的 UNIX 开源运动中过来的,对开源世界存在好感。而在国内大学,开源这个词还是比较遥远的,这不免我又得吐槽学校机房的那一台台 Windows XP和上面的 VC++ 6,数据库实验用的 SQL Server,连唯一在操作系统实验中使用的 Linux 系统都是装在虚拟机上的。这也可能是利益原因,因为使用 Windows 下的那堆东西可以申请经费,然后买个盗版盘,轻松装机,感觉还不错。

我得开始自我反思了,放在 Github 上的几个小玩意儿,极其混乱,文档不足,代码格式不规范。俨然已经将 Github 当成堆放代码的地方了,而不是展示作品和协作开发的地方,虽然水平还不是很高,至少要有模有样。