本文章内的内容来自开源代码预处理,如需要看完整版本,请移步。
1. 显式声明(版权持有人,年份,许可证类型),比如:
/* Copyright 1992 Karl Berry
Copyright 2007 TeX Users Group
Copyright 2014 CXXXX XX
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA. */
2. 说明文档
可以使纯文本,也可以是Markdown,不建议直接上DVI/PDF之类的二进制文件,通常的说明文档涵盖:README(自述文件,如果比较多,可以写个扩展名多分出来几个,比如README.coding[代码风格描述]),INSTALL(安装流程),ChangeLog(变更日志)。
开源的程序和库,一定要给其他的开发者提供足够的信息,比如使用的语言版本,库版本,编译器版本,构建系统版本。有没有注释其实也无所谓,对于三四万行的库,没有注释对于部分程序员还是可以接受的(比如我会用gtags和htags生成html来读,跳来跳去虽然有些麻烦但是还好。从main开始读)。对于构建系统,使用autotools,bakefile,CMake或者Scons的,一定要给其他开发者提供足够的说明,当然,对于非Unix平台的程序,有些也是提供.sln文件的。
3. 对于使用GPL的程序和库,在提供下载的地方一定要把源码和可执行文件放在一起供用户下载,源码一般打包成.tar.gz/.tar.xz,推荐后者,压缩比比较高。这在某些许可证授权下的程序里面是很重要的。下载的地点最好是个不容易变化的地址,最好不要放在网盘里面。
4. 对于代码的整理,一是文件名要有一定含义,不能prog0.c这样的编号,如果你非要这种编号的话,最好在源文件开头的时候说明到底是干嘛的,一行都可以。代码的缩进风格,这是个人习惯,但是也有相关的工具可以使用,比如GNU项目的indent工具。至于变量、函数、结构体命名的习惯,随便找一个coding standard来读即可。尽量不要混用不同的代码风格,比如把下划线命名和Camel Case混在一起,这样的代码会让人抓狂。一行代码的最长长度最好不超过78个字(不过此条对于部分C++项目失效)。还有一点值得注意:别把密码账号信用卡开房日期什么的写到代码里面。除非你删掉代码仓库,否则有你傻X的一天。
5. 文档系统,可以以单独的文档出现,比如用LaTeX/DocBook等写个比较系统的文档,这类文档需要作者花费一定的时间,而这类文档也是最好懂的。其次使用Doxygen之类的将注释抽取出来形成文档,这种文档的可读性还是有一些的,前提是你注释功夫好。
首先你要选择你准备采用的发布协议。例如 gpl 啊 bsd 啊 apache 啊 mit 啊等等。然后,你可以参考该协议中给你的建议。一般而言协议中会建议你在每个源文件头都加上版权信息,这个信息对于每个不同的协议不同。你可以打开一个对应协议的开源项目,查看里面的代码头,一般这个头是协议的简化版。把每个文件都加上版权信息,然后在你的项目的主目录中存放你使用的协议的「完整全文」,这个文件一般可以取名为 COPYING ,当然你也可以取名为用户可以理解的任何名字。源代码仓库中包含版权协议的完整全文,并且每个源代码头都包含版权声明简化版。然后这个代码要「发布」出去(发布的方式与场所你可以任意选择)。这就满足了开源的基本要素。就开源本身来说,以某个开源的协议发布,就算作开源。至于其他的事情都是「可选」的,你做了更多,可以更好的宣传你的项目,但并不是强制的。
开源程序注意事项