C程序开发规范

 

程序设计规范

 

1. 文件夹与文件的命名规则

1.1 文件夹命名

 

① 根据系统设计所规定的结构，建立相应的文件夹，根据需要建立子文件夹

② 文件夹的名称应尽量能够表达其意义，尽量使用英文命名，绝对不能汉字

③ 文件夹名称的必须全部使用小写字母 (如 “ /example ” )

1.2 文件命名

 

① 文件的名称应尽量能够表达其意义，尽量使用英文命名，绝对不能汉字

② 文件名称全部使用小写字母(确保平台兼容)

③ 文件名称一般采用”xxx_yyy.ext”格式，xxx(3-4个字母)表示分类，yyy(字母数自定)表示操作 (如 “ /example/exp_edit.htm ”)

2. 程序书写规则

2.1 变量命名

 

所有变量必须能够反映变量的作用，采用如下命名规则：

⑴ 常数命名约定

用 Const 语句创建真正的常数。这个约定使用大小写混合的格式，并以“con”作为常数名的前缀。例如：

conYourOwnConstant

 

⑵ 变量命名约定

出于易读和一致性的目的，请在 VBScript 代码中使用以下变量命名约定：

类型

前缀

示例

 

Boolean

Bln

blnFound

 

Byte

byt

bytRasterData

 

Date (Time)

dtm

dtmStart

 

Double

dbl

dblTolerance

 

Error

err

errOrderNum

 

Integer

int

intQuantity

 

Long

lng

lngDistance

 

Object

obj

objCurrent

 

Single

sng

SngAverage

 

String

str

strFirstName

 

 

⑶ 变量作用域前缀

随着 Script 代码长度的增加，有必要快速区分变量的作用域。在类型前缀前面添加一个单字符前缀可以实现这一点，而不致使变量名过长。

作用域

前缀

示例

 

过程级

无

dblVelocity

 

Script级

s

sblnCalcInProgress

 

全程级

g

gblnCalcInProgress

 

 

⑷ 描述性变量名和过程名

变量名或过程名的主体应使用大小写混合格式，并且尽量完整地描述其目的。另外，过程名应以动词开始，例如 InitNameArray 或 CloseDialog。对于经常使用的或较长的名称，推荐使用标准缩写以使名称保持在适当的长度内。通常多于 32 个字符的变量名会变得难以阅读。使用缩写时，应确保在整个 Script 中保持一致。

 

对象命名约定，下表列出了 VBScript 中可能用到的对象命名约定（推荐）：

对象类型

前缀

示例

 

文本框

txt

txtLastName

 

列表框

lin

linVertical

 

复选框

chk

chkReadOnly

 

组合框、

下拉列表框

cbo

cboEnglish

 

标签

lbl

lblHelpMessage

 

命令按钮

cmd

cmdExit

 

框架

fra

fraLanguage

 

图像

img

imgIcon

 

直线

lst

lstPolicyCodes

 

公共对话框

dlg

dlgFileOpen

 

水平滚动条

Hsb

hsbVolume

 

垂直滚动条

vsb

vsbRate

 

 

⑸ 代码注释约定

所有过程的开始部分都应有描述其功能的简要注释。当传递给过程的参数的用途不明显，或过程对参数的取值范围有要求时，应加以说明。如果过程改变了函数和变量的返回值（特别是通过参数引用来改变），也应在过程的开始部分描述该返回值。

 

过程开始部分的注释应包含以下区段标题。相关样例，请参阅后面的“格式化代码”部分。

 

区段标题 注释内容

目的 过程的功能（不是实现功能的方法）。

假设 其状态影响此过程的外部变量、控件或其他元素的列表。

效果 过程对每个外部变量、控件或其他元素的影响效果的列表。

输入 每个目的不明显的参数的解释。每个参数都应占据单独一行并有其内部注释。

返回 返回值的解释。

请记住以下几点：

 

每个重要的变量声明都应有内部注释，描述变量的用途。

应清楚地命名变量、控件和过程，仅在说明复杂细节时需要内部注释。

应在 Script 的开始部分包含描述该 Script 的概述，列举对象、过程、运算法则、对话框和其他系统从属物。有时一段描述运算法则的假码是很有用的。

格式化代码

应尽可能多地保留屏幕空间，但仍允许用代码格式反映逻辑结构和嵌套。以下为几点提示：

标准嵌套块应缩进 4 个空格。

过程的概述注释应缩进 1 个空格。

概述注释后的最高层语句应缩进 4 个空格，每一层嵌套块再缩进 4 个空格。例如：

'*********************************************************

' 目的： 返回指定用户在 UserList 数组中第一次出现的位置。

' 输入： strUserList(): 所查找的用户列表。

' strTargetUser: 要查找的用户名。

' 返回： strTargetUser 在 strUserList 数组中第一次出现时的索引。

' 如果目标用户未找到，返回 -1。

' 日期： Designed by MS 2000/9/12

'*********************************************************

 

Function intFindUser (strUserList(), strTargetUser)

Dim i ' 循环计数器。

Dim blnFound ' 发现目标的标记。

intFindUser = -1

i = 0 ' 初始化循环计数器。

Do While i <= Ubound(strUserList) and Not blnFound

If strUserList(i) = strTargetUser Then

blnFound = True ' 标记设为 True。

intFindUser = i ' 返回值设为循环计数器。

End If

i = i + 1 ' 循环计数器加 1。

Loop

End Function

 

2.2 公用函数库

 

① 所有公用函数文件均放在“ /include ”目录下，统一管理，并作适当归类和调整

② 所有公用函数必须在函数前以注释方式书写函数作用，参数定义和返回值,例如：

2.4 注释

 

① 注释尽量使用中文

② 每个程序开始部分必须有以下注释：

程序名称、程序描述、实现功能、设计人员、设计日期

③ 程序代码部分必须有足够的代码片段的注释，表达清楚该程序片段的编写意图和实现原理

2.5 程序结构

 

① 程序代码中要有足够的容错处理功能

② 报表程序与查询程序应该具有灵活性，尽量提供给用户足够的选择

③ 程序代码结构必须层次清楚，适当使用空行分段

3. 界面设计规则

 

1. 界面设计尽量美观、实用、统一

2. 界面设计应尽量参考美工的建议

4. 测试规则

 

1. 程序编写完成后，应进行必要的测试。

2. 测试用例要覆盖各功能模块。

命名规则

比较著名的命名规则当推Microsoft公司的“匈牙利”法，该命名规则的主要思想是“在变量和函数名中加入前缀以增进人们对程序的理解”。例如所有的字符变量均以ch为前缀，若是指针变量则追加前缀p。如果一个变量由ppch开头，则表明它是指向字符指针的指针。

 

“匈牙利”法最大的缺点是烦琐，例如

 

int i, j, k;

 

float x, y, z;

 

倘若采用“匈牙利”命名规则，则应当写成

 

int iI, iJ, ik; // 前缀 i表示int类型

 

float fX, fY, fZ; // 前缀 f表示float类型

 

如此烦琐的程序会让绝大多数程序员无法忍受。

 

据考察，没有一种命名规则可以让所有的程序员赞同，程序设计教科书一般都不指定命名规则。命名规则对软件产品而言并不是“成败悠关”的事，我们不要化太多精力试图发明世界上最好的命名规则，而应当制定一种令大多数项目成员满意的命名规则，并在项目中贯彻实施。

 

3.1 共性规则

本节论述的共性规则是被大多数程序员采纳的，我们应当在遵循这些共性规则的前提下，再扩充特定的规则，如3.2节。

 

 

l 【规则3-1-1】标识符应当直观且可以拼读，可望文知意，不必进行“解码”。

 

标识符最好采用英文单词或其组合，便于记忆和阅读。切忌使用汉语拼音来命名。程序中的英文单词一般不会太复杂，用词应当准确。例如不要把CurrentValue写成NowValue。

 

 

l 【规则3-1-2】标识符的长度应当符合“min-length && max-information”原则。

 

几十年前老ANSI C规定名字不准超过6个字符，现今的C++/C不再有此限制。一般来说，长名字能更好地表达含义，所以函数名、变量名、类名长达十几个字符不足为怪。那么名字是否越长约好？不见得! 例如变量名maxval就比maxValueUntilOverflow好用。单字符的名字也是有用的，常见的如i,j,k,m,n,x,y,z等，它们通常可用作函数内的局部变量。

 

 

l 【规则3-1-3】命名规则尽量与所采用的操作系统或开发工具的风格保持一致。

 

例如Windows应用程序的标识符通常采用“大小写”混排的方式，如AddChild。而Unix应用程序的标识符通常采用“小写加下划线”的方式，如add_child。别把这两类风格混在一起用。

 

 

l 【规则3-1-4】程序中不要出现仅靠大小写区分的相似的标识符。

 

例如：

 

int x, X; // 变量x 与 X 容易混淆

 

void foo(int x); // 函数foo 与FOO容易混淆

 

void FOO(float x);

 

 

l 【规则3-1-5】程序中不要出现标识符完全相同的局部变量和全局变量，尽管两者的作用域不同而不会发生语法错误，但会使人误解。

 

 

l 【规则3-1-6】变量的名字应当使用“名词”或者“形容词＋名词”。

 

例如：

 

float value;

 

float oldValue;

 

float newValue;

 

 

l 【规则3-1-7】全局函数的名字应当使用“动词”或者“动词＋名词”（动宾词组）。类的成员函数应当只使用“动词”，被省略掉的名词就是对象本身。

 

例如：

 

DrawBox(); // 全局函数

 

box->Draw(); // 类的成员函数

 

 

l 【规则3-1-8】用正确的反义词组命名具有互斥意义的变量或相反动作的函数等。

 

例如：

 

int minValue;

 

int maxValue;

 

 

int SetValue(…);

 

int GetValue(…);

 

 

2 【建议3-1-1】尽量避免名字中出现数字编号，如Value1,Value2等，除非逻辑上的确需要编号。这是为了防止程序员偷懒，不肯为命名动脑筋而导致产生无意义的名字（因为用数字编号最省事）。

 

3.2 简单的Windows应用程序命名规则

作者对“匈牙利”命名规则做了合理的简化，下述的命名规则简单易用，比较适合于Windows应用软件的开发。

 

 

l 【规则3-2-1】类名和函数名用大写字母开头的单词组合而成。

 

例如：

 

class Node; // 类名

 

class LeafNode; // 类名

 

void Draw(void); // 函数名

 

void SetValue(int value); // 函数名

 

 

l 【规则3-2-2】变量和参数用小写字母开头的单词组合而成。

 

例如：

 

BOOL flag;

 

int drawMode;

 

 

l 【规则3-2-3】常量全用大写的字母，用下划线分割单词。

 

例如：

 

const int MAX = 100;

 

const int MAX_LENGTH = 100;

 

 

l 【规则3-2-4】静态变量加前缀s_（表示static）。

 

例如：

 

void Init(…)

 

{

 

static int s_initValue; // 静态变量

 

…

 

}

 

 

l 【规则3-2-5】如果不得已需要全局变量，则使全局变量加前缀g_（表示global）。

 

例如：

 

int g_howManyPeople; // 全局变量

 

int g_howMuchMoney; // 全局变量

 

 

l 【规则3-2-6】类的数据成员加前缀m_（表示member），这样可以避免数据成员与成员函数的参数同名。

 

例如：

 

void Object::SetValue(int width, int height)

 

{

 

m_width = width;

 

m_height = height;

 

}

 

 

l 【规则3-2-7】为了防止某一软件库中的一些标识符和其它软件库中的冲突，可以为各种标识符加上能反映软件性质的前缀。例如三维图形标准OpenGL的所有库函数均以gl开头，所有常量（或宏定义）均以GL开头。

 

作者Blog： http://blog.youkuaiyun.com/onlytiancai/