开发规范编码排版、注释规范.doc

-
. z.
软件开发规
?试行版?
Version
?编程语言开发规?
2004-6-3
-
. : Date: // 作者、版本及完成日期
Description: // 用于详细说明此程序文件完成的主要功能，与其他模块
// 或函数的接口，输出值、取值围、含义及参数间的控
// 制、顺序、独立或依赖等关系
Others: // 其它容的说明
History: // 修改历史记录列表，每条修改记录应包括修改日期、修改
// 者及修改容简述
#Date Author Modification
1
2
*************************************************/
2-3：函数头部应进展注释，列出：函数的目的/功能、输入参数、输出参数、返回值、调用关系〔函数、表〕等。
例如：建议所有文件使用该格式；java文件使用javadoc要求的格式
/*************************************************
Description: //函数功能、性能等的描述
Pre-Conditions： // 前置条件
Param: // 输入参数说明，包括每个参数的作用、取值说明及参数间关系。
-
. z.
Return: // 函数返回值的说明
Others: // 其它说明
*************************************************/
2-4：边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除。
要求：每8行，必须要有一条注释
2-5：注释的容要清楚、明了，含义准确，防止注释二义性。
说明：错误的注释不但无益反而有害。
2-6：防止在注释中使用缩写，特别是非常用缩写。
说明：在使用缩写时或之前，应对缩写进展必要的说明。
2-7：注释应与其描述的代码相近，对代码的注释应放在其上方或右方〔对单条语句的注释〕相邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开。
例如：如下例子不符合规。
例1：
/* get replicate sub system inde* and net indicator */
repssn_ind = ssn_data[inde*].repssn_inde*;
repssn_ni = ssn_data[inde*].ni;
例2：
repssn_ind = ssn_data[inde*].repssn_inde*;
repssn_ni = ssn_data[inde*].ni;
/* get replicate sub system inde* and net indicator */
应如下书写
// get replicate sub system ind