研究小组程序和文档开发规范(初稿)
李若, rli@math.pku.edu.cn，
Time-stamp: <2004-09-23 13:10:00 rli>
总纲
我们指定下列规范，是期望达成下述目标：
- 对小组成员的学习和研究成果能够进行准确评价；
- 使得小组成员的学习和研究成果能够在小组内共享，作为小组的永久存档资源；
- 使得小组成员养成良好的学习习惯；
- 使得小组成员迅速掌握高效规范的工作模式；
下述工作模式，要求已经开展研究工作的研究生同学尽量尽快向此规范靠拢，还
未开展研究工作的研究生同学从开始研究工作开始，就遵循此规范工作。
此规范将在试行过程中逐步修订、细化和完善。
程序开发
小组成员开发的程序及其相关文档，必须至少在小组内部可以共享，开发者和小
组共同享有版权。
对程序语言的一般要求
小组成员要求主要使用 C, C++, FORTRAN(77, 90), MATLAB 语言进行程序的开发，
如果采用其他语言，要求事先和导师讨论，并在最后的程序产品中附加该语言的
详尽文档，以能够使得继续相关工作的后继者能够在无对面交流的情况下顺利进
行进一步的工作。
对程序外程序文档的一般要求
完成一个研究任务的整个程序，要求必须维护相关的说明文档，包括：
- README 文件：对整个程序的功能和任务进行简单介绍；
- CHANGELOG 文件：记录整个开发过程的重要开发和修改过程；
- INSTALL 文件：如何安装该程序的说明和简单使用介绍；
- COPYING 文件：版权声明；
- AUTHORS 文件：程序的创作者及其联系方式，若获资助，在此声明；
作为一个简单的、只是完成比较细致的特定功能的小规模程序，可以不必另外维
护使用说明书，但若有使用说明书更好；对于规模稍微大一点、或者可以进一步
进行发展达到比较大规模的程序，必须提供详尽的使用说明书。
和程序的同时，需要提供 LATEX，HTML(XML) 或者 DOXYGEN(推荐) 格式的数学
描述文档，这个文档要求从开发伊始，就必须具备，随着研究的进步、程序的实
现同步进行维护，从而能够完整的跟踪整个研究过程。
对程序中注释的一般要求
- 程序中的注释，必须使用中文书写；
- 程序中的注释，按字符计算，不得少于整个文件的 30%；
- 原则上，每个程序函数和模块都必须给出注释；
- 程序中使用特定算法的位置，必须给出算法的详细描述，并给出文献参考；
- 整个程序和注释，加上其中提到的引用，基本上应该是自封闭的；
- 程序的注释必须和相应代码放在文件的相同位置，不得分别维护；
C 和 C++ 程序的要求
使用 C 或者 C++ 进行开发，头文件和实现文件必须分开。每个实现文件原则
上不允许超过 3000 行代码长度。源码的书写风格必须遵循一个已有的流行的
书写风格(推荐 gnu 或 stroustrup)，变量命名规范以和数学公式中尽量符合
并试图遵守匈牙利命名规则为准。
使用 C 或者 C++ 进行开发，要求使用文档维护工具 Doxygen 或者 KDoc 进行
文档维护工作。请阅读选用的工具的说明书了解程序中文档的书写方式。
这里可以下载一个使用 C++ 进行开发的范例，包括例子程序，程序外文档和
这些程序和文档最后产生的 HTML 格式的文档的样子。
FORTRAN 程序的要求
使用 FORTRAN 进行开发，原则上对于 FORTRAN 77 不得使用 Free Form 书写
风格，对于 FORTRAN 90 推荐使用 Free Form 书写风格。使用 Free Form 书
写风格时，行长建议不超过 80 字符；建议使用两个空格作为缩进标准；不建
议程序中使用大小写混排命名；不建议使用隐含类型约定。
使用 FORTRAN 进行开发，要求使用文档维护工具 Robodoc 进行文档维护工作。
该软件的文档在 李若主页 上有中文译本。
MATLAB 程序的要求
待定。
文档开发
小组成员开发的各类文档，必须至少在小组内部可以共享，开发者和小组共同享
有版权。
我们研究小组主要需要维护的文档为两类，一类是 TEX 格式的数学描述为主
的文档，另一类为网页(HTML 或者 XML)格式的文档。对于两类文档的开发和
维护方式，暂时还没有格式上的任何规定。我目前的看法为发展为下列方式
比较方便：
- 使用 CVS 进行版本管理；
- 使用 Doxygen 进行网页文档的开发格式；
使用 CVS 的理由在下面叙述，使用 Doxygen 的格式开发网页的理由在于：我
们的网页中会涉及到较多数学公式，Doxygen 会自动处理数学公式，使得网页
的书写效率大大提高。如果需要网页有比较好的美学效果，可以使用 HTML 和
Doxygen 格式的文档相互作用得到。
小组开发的演示文稿类的文档，为 TEX 格式源码的 PDF 文件以及 POWERPOINT
格式的文件，我们正在制作相应的模板，所有演示文稿文档均需要按照此模板
样式制作。
开发过程管理
建议使用版本管理软件(如 CVS)进行开发过程管理，这样可以记录整个程序或
者文档的开发历史。建议方式为，每位导师建立一个服务器端，研究生应该在
导师的服务器上建立帐号，研究生的所有程序和文档至少应该每个星期提交到
服务器上(建议每个工作日提交)。这样的使用方法的好处是：
- 整个开发过程非常清晰，没有混乱，不会出现文件丢失之类问题；
- 研究生的工作情况被详尽记录，每次提交的历史均可重现；