软件源代码编写规范

软件源代码编写规范

1. 目的 ....................................................................................................... 3

2. 适用范围............................................................................................... 3

3. 规范内容............................................................................................... 3

3.1. 基本要求 ..................................................................................... 3

3.1.1. 程序结构要求 .................................................................... 3

3.1.2. 可读性要求 ........................................................................ 3

3.1.3. 结构化要求 ........................................................................ 4

3.1.4. 正确性与容错性要求 ........................................................ 4

3.2. 标识符命名及书写规则： ......................................................... 5

3.2.1. 基本规则 ............................................................................ 5

3.3. 注释.............................................................................................. 5

3.3.1. 注释及格式要求 ................................................................ 5

3.3.2. 源代码文件的注释 ............................................................ 6

3.3.3. 函数或过程的注释 ............................................................ 6

3.3.4. 语句的注释 ........................................................................ 6

3.3.5. 常量和变量的注释 ............................................................ 6

3.3.6. 文件的注释模板 ................................................................ 7

3.4. 其他要求 ..................................................................................... 7

软件源代码编写规范 3 / 7

1. 目的

良好的编程风格是提高程序可靠性非常重要的手段，也是大型项目多人合作开发的技术基础。本规范的目的在于通过规范定义来避免不好的编程风格，增强程序的易读性，便于自己和其它程序员理解。

2. 适用范围

本规定适用于所有软件的源程序编写。客户有特殊要求时，则遵循客户提出的要求。

3. 规范内容

3.1. 基本要求

3.1.1. 程序结构要求

1） 程序结构清晰，简单易懂，单个函数的程序代码行数建议不超过100行，函数功能尽量单一。

2） 目标明确，代码简洁清晰，单行代码最大字符数建议不超过120个。

3） 避免随意定义全局变量，尽量使用局部变量。

3.1.2. 可读性要求

1） 在保证代码可读性的前提下提高代码执行效率，对执行效率要求比较高的关键代码可以除外。

2） 保持注释与代码完全一致，当代码更改后及时更新相应的注释。

3） 每个源程序文件，都有文件头说明，说明内容见“源代码文件的注释”。

软件源代码编写规范 4 / 7

4） 每个函数，都有函数头说明，说明内容见“函数或过程的注释”。

5） 函数中尽量减少输出参数的使用。

6） 主要变量（结构、联合、类或对象）定义或引用时，添加注释，反映其含义。

7） 处理过程的每个主要阶段、典型算法前都应有相应的简单说明性注释。

8） 利用缩进来显示程序的逻辑结构，缩进量一致并以Tab键为单位，不建议使用空格。

9） 循环、分支层次尽量不要超过五层。建议多层循环在每层循环结束语句后注释说明退出的相应层次。

10） 注释的位置可以在相应代码的上一行或同一行。

11） 一目了然的语句不加注释。

12） 常量定义（DEFINE）有相应说明。

3.1.3. 结构化要求

1） 不建议使用GOTO语句。

2） 用 IF 语句来强调只执行两组语句中的一组。不建议使用 ELSE GOTO

和 ELSE RETURN。

3） 避免从循环引出多个出口。

4） 避免不必要的分支。

3.1.4. 正确性与容错性要求

1） 除特殊使用情况，所有变量在定义时建议进行初始化。

2） 对所有的用户输入，建议在函数或程序开始前进行合法性检查。

3） 在修改错误前首先考虑是否对其它代码的影响，避免因此产生新的错误。

4） 使用规范的容错语句，提供完善的异常处理措施，如文件能否逻辑锁定、打印机是否联机等,对于明确的错误,要有明确的容错代码提示用户。

软件源代码编写规范 5 / 7

3.2. 标识符命名及书写规则：

3.2.1. 基本规则

1） 这里的标识符是指编程语言中语法对象的名字，它们有常量名、变量名、函数名、类和类型名、文件名等，标识符的基本语法是以字母开始，由字母数字及下划线组成的单词。建议全局变量用g_开头，局部变量用m_开头。

2） 标识符本身最好能够表明其自身的含义，以便于使用和他人阅读。按其在应用中的含义由一个或多个词组成。可以是英文词或中文拼音词。

3） 标识符的基本形式建议为：

范围标志 + 类型标志 + 含义

范围标志为g_、m_或者其他变量作用范围标志；类型标志可以为变量的类型，如str（string类型）、i（int类型）、f（float类型）、txt（文本框控件类型）等；含义可以是任意的词组，当标识符由多个词组成时，每个词的第一个字母大写，其余全部小写。例如：m_strMyExample。

常量标识符全部大写。中文词由中文描述含义的每个汉字的头一个拼音字母组成。英文词尽量不缩写，如果有缩写，在同一系统中对同一单词使用相同的表示法。

4） 标识的总长度尽量不要超过32个字符。

3.3. 注释

3.3.1. 注释及格式要求

注释总是加在程序的需要一个概括性说明或不易理解或易理解错的地方。注释应语言简炼、易懂而又准确，所采用的语种首选是中文，如有输入困难、编译环境限制或特殊需求也可采用英文。

软件源代码编写规范 6 / 7

3.3.2. 源代码文件的注释

1） 在文件的头部应标明程序名称，它所完成的主要功能。

2） 文件的创建者、创建时间、版本。

3） 公司名称、版权。

4） 阶段测试结束后，主要修改活动的修改人、时间、简单原因说明列表。

5） 维护过程中需要修改程序时，应在被修改语句前面注明修改时间和原因说明。

3.3.3. 函数或过程的注释

1） 在函数头部应对函数进行功能和参数（值参、变参）说明；

2） 在函数的主体部分，如算法复杂时，应以注释的方式对其算法结构作出说明；

3） 函数申请过全局资源且有可能导致资源紧张应加以注明(如内存，文件柄等)；

4） 函数有副作用建议以十分醒目的方式（如加!号等）注明。

3.3.4. 语句的注释

1） 应对不易理解的分支条件表达式加注释；

2） 不易理解的循环，应说明出口条件；

3） 过长的函数实现，应将其语句按实现的功能分段加以概括性说明；

4） 供别的文件或函数调用的函数，避免使用全局变量交换数据。

3.3.5. 常量和变量的注释

在常量名字(或有宏机制的语言中的宏)声明后应对该名字作适当注释，注释说明的要点是：

1） 被保存值的含义(必须)；

2） 合法取值的范围(可选)；

软件源代码编写规范 7 / 7

3） 全局量需要对以上逐点做充分的说明。

3.3.6. 文件的注释模板

/*

* =========================================================

* 文件名: PlotItemSetting.h

* 描述: 曲线设置头文件

* 版本号: 1.1

* 创建日期: 2010-4-1 15:52:03

* IDE环境: Microsoft Visual Studio 2005 ( sp1 )

* 字符编码: UTF-8

* 作者: XXX

* 版权所有: XXXXXX技术有限公司

* 版本修改历史:

* 2011-4-1 XXX:创建文件

* 2011-4-22 XXX:增加方法Sub、Add

* ===========================================================

*/

3.4. 其他要求

1） 项目组可以根据实际需要，对本规范内的条款进行补充说明，或者增加新的条款，但不得与本规范的原条款相冲突。

2） 如补充条款与本规范不一致的，以本规范为准。