首页 > 代码库 > 开源程序注意事项

开源程序注意事项

本文章内的内容来自开源代码预处理,如需要看完整版本,请移步。

 

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 ,当然你也可以取名为用户可以理解的任何名字。源代码仓库中包含版权协议的完整全文,并且每个源代码头都包含版权声明简化版。然后这个代码要「发布」出去(发布的方式与场所你可以任意选择)。这就满足了开源的基本要素。就开源本身来说,以某个开源的协议发布,就算作开源。至于其他的事情都是「可选」的,你做了更多,可以更好的宣传你的项目,但并不是强制的。