VC代码书写规范文档格式.docx
《VC代码书写规范文档格式.docx》由会员分享,可在线阅读,更多相关《VC代码书写规范文档格式.docx(15页珍藏版)》请在冰豆网上搜索。
、"
+="
,算术操作符"
+"
、"
%"
,逻辑操作符"
"
,位域操作符"
<
^"
等双目操作符的前后加空格。
if(current_time>
=MAX_TIME_VALUE)
a=b+c;
a*=2;
a=b^2;
1.9.3"
!
~"
++"
--"
(地址运算符)等单目操作符前后不加空格。
*p='
a'
;
//内容操作"
*"
与内容之间
flag=!
isEmpty;
//非操作"
p=&
mem;
//地址操作"
与内容之间
i++;
//"
"
1.9.4"
->
."
前后不加空格。
p->
id=pid;
指针前后不加空格
1.9.5if、for、while、switch等与后面的括号间应加空格,使if等关键字更为突出、明显。
if((a>
=b)&
(c>
d))
2注释格式约定
2.1一般情况下,源程序有效注释量必须在20%以上。
注释的原则是有助于对程序的阅读理解,注释不宜太多也不能太少,注释语言必须准确、易懂、简洁。
2.2建议单行注释使用“//……”,多行注释使用“/*……*/”。
为了注释格式的统一,一般情况下均采用“//……”的注释格式。
2.3说明性文件(如头文件.h文件、.inc文件、.def文件、编译说明文件.cfg等)头部应进行注释,注释必须列出:
版权说明、文件名、作者、版本号、创建日期、功能描述、与其它文件的关系、修改日志等,头文件的注释中还应有函数功能简要说明。
下面这段头文件的头注释比较标准。
////////////////////////////////////////////////////////////////
//版权所有(C),1999-2002,武汉华工赛百数据系统有限公司
//文件名:
Global.h
//作者:
Tomas
//版本号:
1.00
//创建日期:
2002-2-4
//功能描述:
用于详细说明此程序文件完成的主要功能,与其它类之间的依赖关//系等
//备注:
其它内容的说明
//修改日志:
//1.修改日期:
//修改者:
//修改原因:
//修改内容:
//2....
///////////////////////////////////////////////////////////////
2.4源文件头部应进行注释,列出:
版权说明、文件名、作者、版本号、创建日期、模块描述、修改日志等。
下面这段源文件的头注释比较标准。
Global.cpp
//模块描述:
描述本文件内部各模块之间的关系以及与其它文件之间的接口等
2.5函数头部应进行注释,列出:
函数名称、作者、创建日期、功能描述、输入参数、输出参数、返回值、调用关系(函数、表)、修改日志等。
下面这段函数的注释比较标准。
//函数名称:
(此项仅用于全局函数或非文件的创建者编写的函数)
//输入参数:
//输出参数:
//返回值:
//被本函数调用的函数清单:
//调用本函数的函数清单:
//被访问的表:
(此项仅用于牵扯到数据库操作的函数)
//被修改的表:
2.6边写代码边注释,修改代码同时修改相应的注释,以保证注释与代码的一致性。
不再有用的注释要删除。
注释的内容要清楚、明了,含义准确,防止注释二义性。
避免在注释中使用缩写,特别是非常用缩写。
2.7注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。
//初始化保存累加和的临时变量为0
intsum=0;
//累加求和
for(count=0;
count<
num;
count++)
sum+=data[count];
2.8对于所有有物理含义的变量、常量,如果其命名不是充分自注释的,在声明时都必须加以注释,说明其物理含义。
变量、常量、宏的注释应放在其上方相邻位置或右方。
//圆弧的起点坐标
CPointm_ptBegin;
//圆弧的终点坐标
CPointm_ptEnd;
2.9数据结构声明(包括数组、结构、类、枚举等),如果其命名不是充分自注释的,必须加以注释。
对数据结构的注释应放在其上方相邻位置,不可放在下面;
对结构中的每个域的注释放在此域的右方。
//选择工具中出现的几种状态
typedefenumtagSTATUS
{
ISMOVE,//图形处于移动状态
ISROTATE,//图形处于旋转状态
ISRESIZE,//图形处于放大状态
NOSELECT//图形处于没有选择状态
}STATUS;
2.10全局变量要有较详细的注释,包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明。
2.11注释与所描述内容进行同样的缩排。
将注释与其上面的代码用空行隔开。
2.12避免在一行代码或表达式的中间插入注释。
在代码的功能、意图层次上进行注释,提供有用、额外的信息。
2.13在程序块的结束行右方加注释标记,以表明某程序块的结束。
if(a>
b)
for(i=0;
i<
a;
i++)
}//endfor
}//endif
else
}//endelse
2.14注释应考虑程序易读及外观排版的因素,使用的语言若是中、英兼有的,建议多使用中文,除非能用非常流利准确的英文表达。
3通用命名约定
3.1标识符的命名要清晰、明了,有明确含义,同时使用完整的单词或大家基本可以理解的缩写,避免使人产生误解。
较短的单词可通过去掉“元音”形成缩写;
较长的单词可取单词的头几个字母形成缩写;
一些单词有大家公认的缩写,见附录7.1。
temp可缩写为tmp;
flag可缩写为flg;
message可缩写为msg;
3.2变量和函数名一般采用首字母大写、大小写组合的命名方式,单词之间不要使用下划线(表示范围的前缀,如“m_”等除外)。
常量一般采用全部大写的命名方式,单词之间用下划线隔开。
intnStrokeWidth;
BOOLbAutoSnapToGrid;
voidShowLayer(CDC*pDC);
constONLINE_DISTANCE8
3.3除非必要,不要用数字或较奇怪的字符来定义标识符。
3.4用正确的反义词组命名具有互斥意义的变量或相反动作的函数等。
下面是一些在软件中常用的反义词组。
Add/remove
begin/end
create/destroy
insert/delete
first/last
get/release
increment/decrement
set/get
add/delete
lock/unlock
open/close
min/max
old/new
start/stop
next/previous
source/target
show/hide
send/receive
source/destination
cut/paste
up/down
4常量命名约定
4.1常量和宏定义必须具有一定的实际意义。
4.2常量和宏定义必须全部以大写字母来撰写,中间可根据意义的连续性用下划线连接,每一条定义的右侧必须有一简单的注释,说明其作用。
4.3建议用const来定义常量,少用#define来定义常量。
4.4定义宏应加适当的括号以保证宏的正确性。
4.5常用宏定义命名列表见附录7.2。
5变量命名约定
5.1对于变量命名,禁止取单个字符(如i、j、k...),建议除了要有具体含义外,还能表明其变量类型、数据类型等,但i、j、k作局部循环变量是允许的。
变量尽量采用匈牙利命名法,同时结合VC的原则;
一般情况下,变量的取名方式为:
scope>
<
prefix>
qualifier>
有关项目的全局变量必须用g_开始,类成员变量用m_,局部变量若函数较大则可考虑用l_用以显示说明其是局部变量。
前缀
类型
例子
g_
GlobalVariable
g_Servers
C
Classorstructure
CDocument,CPrintInfo
m_
Membervariable
m_pDoc,m_nCustomers
VisualC++常用变量前缀见附录7.3和附录7.4。
5.2防止局部变量与公共变量同名。
若使用了较好的命名规则,那么此问题可自动消除。
5.3结构体类型命名必须全部用大写字母,原则上前面以下划线开始;
结构体变量命名必须用大小写字母组合,用struct作为前缀。
typedefstruct
charszProductName[20];
charszAuthor[20];
charszReleaseDate[16];
charszVersion[10];
}DBS_DATABASE;
DBS_DATABASEg_structDataBase
6函数命名约定
6.1函数命名第一个字母必须使用大写字母,要求用大小写字母组合规范函数命名。
6.2函数名应准确描述函数的功能。
使用动宾词组为执行某操作的函数命名。
如果是OOP方法,可以只有动词(名词是对象本身)。
voidHideLayer(CstringstrLayerName);
CStringGetID();
voidDraw(CDC*pDC);
7附录
7.1常用单词缩写表
规则:
一些单词有大家公认的缩写。
完整单词
缩写
average
avg
back
bk
background
bg
break
brk
buffer
buf
color
cr
control
ctrl
data
dat
decrement
dec
delete
del
document
doc
edit
edt
error
err
escape
esc
flag
flg
form
frm
grid
grd
increment
inc
information
info
initial
init
insert
ins
image
img
label
lab
length
len
list
lst
library
lib
manager
mngr
message
msg
Oracle
Ora
password
pwd
picture
pic
point
pt
position
pos
print
prn
program
prg
server
srv
source
src
statistic
stat
string
str
Sybase
Syb
temp
tmp
text
txt
user
usr
window
wnd
7.2常用宏定义命名列表
符号类型
符号例子
范围
IDR_
标识多个资源共享的类型
IDR_MAINFRAME
1to0x6FFF
IDD_
对话框资源(Dialog)
IDD_SPELL_CHECK
HIDD_
基于对话框的上下文帮助(ContextHelp)
HIDD_SPELL_CHECK
0x20001to0x26FF
IDB_
位图资源(Bitmap)
IDB_COMPANY_LOGO
IDC_
光标资源(Cursor)
IDC_PENCIL
IDI_
图标资源(Icon)
IDI_NOTEPAD
ID_
IDM_
工具栏或菜单栏的命令项
ID_TOOLS_SPELLING
0x8000to0xDFFF
HID_
命令上下文帮助(CommandHelpcontext)
HID_TOOLS_SPELLING
0x18000to0x1DFFF
IDP_
消息框提示文字资源
IDP_INVALID_PARTNO
8to0xDFFF
HIDP_
消息框上下文帮助(Message-boxHelpcontext)
HIDP_INVALID_PARTNO
0x30008to0x3DFFF
IDS_
字符串资源(String)
IDS_COPYRIGHT
1to0x7FFF
对话框内的控制资源(Control)
IDC_RECALC
7.3常用变量前缀表
描述
b
BOOL
Booleanvalue
bEnabled
ch
char
8-bitcharacter
chGrade
TCHAR
16-bitcharacterif_UNICODEisdefined
chName
cx,cy
long,double
Lengthofx,y
cxDistance,cyDistance
dw
DWORD
32-bitunsignedinteger
dwRange
h
HANDLE
HandletoWindowsobject
hWnd
l
LONG
32-bitsignedinteger
lOffset
n
int
Integer(sizedependentonoperatingsystem)
nLength
UINT
Unsignedvalue(sizedependentonoperatingsystem)
lp
FAR*
Farpointer
lpDoc
lpfn
(*fn)()
CallbackFarpointertoCALLBACKfunction
lpfnAbort
lpsz
LPSTR
32-bitpointertocharacterstring
lpszName
LPCSTR
32-bitpointertoconstantcharacterstring
LPCTSTR
32-bitpointertoconstantcharacterstringif_UNICODEisdefined
p
*
Ambientmemorymodelpointer
pDoc
pp
**
Pointertopointer
ppView
sz
char*
StringwithZeroEnd
szText
w
WORD
16-bitunsignedvalue
wPos
x,y
Coordinate
xNavigate,yNavigate
7.4常用控件前缀表
控件名称
文本标签(StaticText)
m_txtInfo
文本编辑框(EditBox)
m_edtPath
普通按钮(Button)
btn
m_btnOK
复选按钮(CheckBox)
chk
m_chkSavePwd
单选按钮(RadioButton)
rad
m_radClockwise
组合框(ComboBox)
cmb
m_cmbFontSize
列表框(ListBox)
lsb
m_lsbFile
水平滚动条(HorizontalScrollBar)
hsb
m_hsbChildFrm
垂直滚动条(VerticalScrollBar)
vsb
m_vsbList
微调控件(Spin)
spn
m_spnSize
进度条控件(Progress)
m_prgLoading
滑杆控件(Slider)
sld
m_sldRatio
列表控件(ListControl)
lsc
m_lscLayer
树型控件(TreeControl)
trc
m_trcContent
图像控件(Picture)
m_picLogo
动画控件(Animate)
ani
m_aniCopy