VC代码书写规范.doc

Central-China Cyber Data System Co., Ltd.VC编程规范版本1.0, 2002-1-30华工赛百VC开发小组1 排版格式约定1.1 程序块采用缩进风格编写，缩进量以一个TAB为单位，每层嵌套缩进一个TAB。1.2 相对独立的程序块之间、变量说明之后必须加空行。空行一般为13行，不允许存在不规则的空行。示例：如下例子不符合规范。if (VK_ESCAPE = nChar) . / program codepLeft.x = m_ptCenter.x - m_nRadius;pLeft.y = m_ptCenter.y - m_nRadius;应如下书写：if (VK_ESCAPE = nChar) . / program codepLeft.x = m_ptCenter.x - m_nRadius;pLeft.y = m_ptCenter.y - m_nRadius;1.3 较长的语句（80字符）要分成多行书写，长表达式要在低优先级操作符处划分新行，操作符放在新行之首，划分出的新行要进行适当的缩进，使排版整齐，语句可读。m_nRadius = (int) sqrt(sqr(m_ptBegin.x - m_ptPrev.x)+ sqr(m_ptBegin.y - m_ptPrev.y);1.4 循环、判断等语句中若有较长的表达式或语句，则要进行适应的划分，长表达式要在低优先级操作符处划分新行，操作符放在新行之首。if (ptInter.y = min(ptStart.y, ptEnd.y)& (ptInter.y ），后不应加空格。说明：采用这种松散方式编写代码的目的是使代码更加清晰。示例如下：1.9.1 逗号、分号只在后面加空格。int a, b, c;1.9.2 比较操作符, 赋值操作符=、 +=，算术操作符+、%，逻辑操作符&、&， 位域操作符= 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.5 if、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 源文件头部应进行注释，列出：版权说明、文件名、作者、版本号、创建日期、模块描述、修改日志等。示例：下面这段源文件的头注释比较标准。/版权所有(C), 1999-2002, 武汉华工赛百数据系统有限公司/文件名：Global.cpp/作者：Tomas/版本号：1.00/创建日期：2002-2-4/模块描述：描述本文件内部各模块之间的关系以及与其它文件之间的接口等/备注：其它内容的说明/修改日志：/ 1. 修改日期：/ 修改者：/ 修改原因：/ 修改内容：/ 2. ./2.5 函数头部应进行注释，列出：函数名称、作者、创建日期、功能描述、输入参数、输出参数、返回值、调用关系（函数、表）、修改日志等。示例：下面这段函数的注释比较标准。/函数名称：/作者：（此项仅用于全局函数或非文件的创建者编写的函数）/创建日期：（此项仅用于全局函数或非文件的创建者编写的函数）/功能描述：/输入参数：/输出参数：/返回值：/被本函数调用的函数清单：/调用本函数的函数清单：/被访问的表：（此项仅用于牵扯到数据库操作的函数）/被修改的表：（此项仅用于牵扯到数据库操作的函数）/备注：/修改日志：/ 1. 修改日期：/ 修改者：/ 修改原因：/ 修改内容：/ 2. ./2.6 边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除。注释的内容要清楚、明了，含义准确，防止注释二义性。避免在注释中使用缩写，特别是非常用缩写。2.7 注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开。/初始化保存累加和的临时变量为0int sum = 0;/累加求和for (count = 0; count b) for (i = 0; i a; i+) . / program code /end for /end ifelse . / program code /end else2.14 注释应考虑程序易读及外观排版的因素，使用的语言若是中、英兼有的，建议多使用中文，除非能用非常流利准确的英文表达。3 通用命名约定3.1 标识符的命名要清晰、明了，有明确含义，同时使用完整的单词或大家基本可以理解的缩写，避免使人产生误解。说明：较短的单词可通过去掉“元音”形成缩写；较长的单词可取单词的头几个字母形成缩写；一些单词有大家公认的缩写，见附录7.1。示例：temp可缩写为 tmp ;flag可缩写为 flg ;message可缩写为 msg ;3.2 变量和函数名一般采用首字母大写、大小写组合的命名方式，单词之间不要使用下划线（表示范围的前缀，如“m_”等除外）。常量一般采用全部大写的命名方式，单词之间用下划线隔开。int nStrokeWidth;BOOL bAutoSnapToGrid;void ShowLayer(CDC *pDC);const ONLINE_DISTANCE 83.3 除非必要，不要用数字或较奇怪的字符来定义标识符。3.4 用正确的反义词组命名具有互斥意义的变量或相反动作的函数等。说明：下面是一些在软件中常用的反义词组。Add/removebegin/endcreate/destroyinsert/deletefirst/lastget/releaseincrement/decrementset/getadd/deletelock/unlockopen/closemin/maxold/newstart/stopnext/previoussource/targetshow/hidesend/receivesource/destinationcut/pasteup/down4 常量命名约定4.1 常量和宏定义必须具有一定的实际意义。4.2 常量和宏定义必须全部以大写字母来撰写,中间可根据意义的连续性用下划线连接,每一条定义的右侧必须有一简单的注释,说明其作用。4.3 建议用const来定义常量，少用define来定义常量。4.4 定义宏应加适当的括号以保证宏的正确性。4.5 常用宏定义命名列表见附录7.2。5 变量命名约定5.1 对于变量命名，禁止取单个字符（如i、j、k.），建议除了要有具体含义外，还能表明其变量类型、数据类型等，但i、j、k作局部循环变量是允许的。变量尽量采用匈牙利命名法，同时结合VC的原则；一般情况下，变量的取名方式为： 有关项目的全局变量必须用g_开始，类成员变量用m_，局部变量若函数较大则可考虑用l_用以显示说明其是局部变量。前缀类型例子g_Global Variableg_ServersCClass or structureCDocument, CPrintInfom_Member variablem_pDoc, m_nCustomersVisual C+常用变量前缀见附录7.3和附录7.4。5.2 防止局部变量与公共变量同名。说明：若使用了较好的命名规则，那么此问题可自动消除。5.3 结构体类型命名必须全部用大写字母,原则上前面以下划线开始;结构体变量命名必须用大小写字母组合, 用struct作为前缀。typedef structchar szProductName20;char szAuthor20;char szReleaseDate16;char szVersion10; DBS_DATABASE;DBS_DATABASE g_structDataBase6 函数命名约定6.1 函数命名第一个字母必须使用大写字母,要求用大小写字母组合规范函数命名。6.2 函数名应准确描述函数的功能。使用动宾词组为执行某操作的函数命名。如果是OOP方法，可以只有动词（名词是对象本身）。void HideLayer(Cstring strLayerName);CString GetID();void Draw(CDC *pDC);7 附录7.1 常用单词缩写表规则：较短的单词可通过去掉“元音”形成缩写；较长的单词可取单词的头几个字母形成缩写；一些单词有大家公认的缩写。完整单词缩写完整单词缩写averageavg backbkbackgroundbg breakbrkbufferbufcolorcrcontrolctrldatadatdecrementdecdeletedeldocumentdoceditedterrorerrescapeescflagflg formfrmgridgrd incrementincinformationinfoinitialinitinsertins imageimglabellab lengthlenlistlst librarylibmanagermngrmessagemsgOracleOra passwordpwdpicturepicpointptpositionpos printprnprogramprgserversrvsourcesrcstatisticstatstringstrSybaseSybtemptmptexttxtuserusrwindowwnd7.2 常用宏定义命名列表前缀符号类型符号例子范围IDR_标识多个资源共享的类型IDR_MAINFRAME1 to 0x6FFFIDD_对话框资源(Dialog)IDD_SPELL_CHECK1 to 0x6FFFHIDD_基于对话框的上下文帮助(Context Help)HIDD_SPELL_CHECK0x20001 to 0x26FFIDB_位图资源(Bitmap)IDB_COMPANY_LOGO1 to 0x6FFFIDC_光标资源(Cursor)IDC_PENCIL1 to 0x6FFFIDI_图标资源(Icon)IDI_NOTEPAD1 to 0x6FFFID_IDM_工具栏或菜单栏的命令项ID_TOOLS_SPELLING0x8000 to 0xDFFFHID_命令上下文帮助(Command Help context)HID_TOOLS_SPELLING0x18000 to 0x1DFFFIDP_消息框提示文字资源IDP_INVALID_PARTNO8 to 0xDFFFHIDP_消息框上下文帮助(Message-box Help context)HIDP_INVALID_PARTNO0x30008 to 0x3DFFFIDS_字符串资源(String)IDS_COPYRIGHT1 to 0x7FFFIDC_对话框内的控制资源(Control)IDC_RECALC8 to 0xDFFF7.3 常用变量前缀表前缀类型描述例子bBOOLBoolean valuebEnabledchchar8-bit characterchGradechTCHAR16-bit character if _UNICODE is definedchNamecx, cylong, doubleLength of x, ycxDistance, cyDistancedwDWORD32-bit unsigned integerdwRangehHANDLEHandle to Windows objecthWndlLONG32-bit signed integerlOffsetnintInteger (size dependent on operating system)nLengthnUINTUnsigned value (size dependent on operating system)nLengthlpFAR*Far pointerlpDoclpfn(*fn)()Callback Far pointer to CALLBACK functionlpfnAbortlpszLPSTR32-bit pointer to character stringlpszNamelpszLPCSTR32-bit pointer to constant character stringlpszNamelpszLPCTSTR32-bit pointer to constant character string if _UNICODE is definedlpszNamep*Ambient memory mode