1. 在.h/.cpp的开头应有一段格式统一的说明,内容包括:
a. 文件名 (FileName);
b. 创建人 (Creator);
c. 文件创建时间 (Date);
d. 简短说明文件功能、用途 (Comment)。
例:
/**/////////////////////////////////////////// //
// FileName: GetVersion.h
// Creator: Liu Haifeng
// Date: 2002-10-28
// Comment: Get file version information
//
/**/////////////////////////////////////////// 2.对于主要功能函数应有注释说明。内容包括:功能、入口/出口参数,必要时还可有备注或补充说明,对于函数中的主要功能代码,也应有注释说明。注释以英文为主。
例:
/**/////////////////////////////////////////// //
//Remarks:
// Check file whether exist
//
//Parameters:
// LPCTSTR lpszPathName : Input full path name
//
//Return values:
// int : Non-zero means success
// Zero means failure
//
/**/////////////////////////////////////////// 3. 每列代码的长度推荐为80列,最长不得超过120列;折行以对齐为准。
例:HANDLE KSOpenFile(const char cszFileName[],
int nMode);
或者:
BOOL KSReadFile(
HANDLE hFile,
void *pvBuffer,
int nReadSize,
int *pnReadSize
); 4. 循环、分支代码,判断条件与执行代码不得在同一行上。
例:正确:
if (n == -2)
n = 1;
else
n = 2;
不得写做:
if (n == -2) n = 1;
else n = 2;
5. 指针的定义,* 号既可以紧接类型,也可以在变量名之前。
例:可写做:int* pnsize;
也可写做:int *pnsize;
但不得写做:int * pnsize;
6. 在类的成员函数内调用非成员函数时,在非成员函数名前必须加上"::"。
例:::Sleep(2000);
7. 函数入口参数有缺省值时,应注释说明。
例:
BOOL KSSaveToFile(
const char cszFileName[],
BOOL bCanReplace /* = TRUE */
);
或者:
BOOL KSSaveToFile(
const char cszFileName[],
BOOL bCanReplace // = TRUE
);
8. else if 必须写在一行。
9. 与‘{’、‘}’有关的各项规定:
9.1‘{’、‘}’应独占一行。在该行内可有注释。
例:正确:
for (i = 0; i < cbLine; i++)
{ // .....
printf("Line %d:", i);
printf("%s\n", pFileLines);
}
不得写做:
for (i = 0; i < cb; i++)
{ printf("Line %d:", i);
printf("%s\n", pFileLines);
} 9.2‘{’必须另起一行,‘{’之后的代码必须缩进一个Tab。‘{’与‘}’必须在同一列上。
例:正确:
if (i > 0)
{
m = 1;
n++;
}
不得写做:
if (i > 0) {
m = 1;
n++;
} 例外:
if (i == 0)
{ ASSERT(FALSE); return; } 9.3 在循环、分支之后若只有一行代码,虽然可省略‘{’、‘}’,但不推荐这么做。若省略后可能引起歧义,则必须加上‘{’、‘}’。
例:正确:
if (n == -2)
n = 1;
else
n = 2; 或者:
if (n == -2)
{ n = 1; }
else if (n != nTemp)
{ n = 2; }
else
{ n = 3; } 不得写做:
if (n == -2)
n = 1;
else if (n != nTemp)
n = 2;
else
n = 3; 不推荐:
if (i < 1)
{ n = 1; }
else
{
if (i == 1)
{ n = 2; }
else
{
if (i > 1)
{ n = 3; }
}
} 10. 与空格有关的各项规定。
10.1 在所有两目、三目运算符的两边都必须有空格。在单目运算符两端不必空格。但在‘->’、‘::’、‘.’、‘[’、‘]’等运算符前后,及‘&’(取地址)、‘*’(取值)等运算符之后不得有空格。
例:正确:
int n = 0, nTemp;
for (int i = nMinLine; i <= nMaxLine; i++)
不得写做:
int n=0, nTemp;
for ( int i=nMinLine; i<=nMaxLine; i++ )
10.2 for、while、if 等关键词之后应有1个空格,再接‘(’,之后无空格;在结尾的‘)’前不得有空格。
例:正确:
if (-2 == n)
不得写做:
if(-2 == n)
或
if ( -2 == n )
等等。
10.3 调用函数、宏时,‘(’、‘)’前后不得有空格。
例:正确:
printf("%d\n", nIndex);
不得写做:
printf ("%d\n", nIndex);
printf( "%d\n", nIndex );
等等。
10.4 类型强制转换时,‘(’‘)’前后不得有空格
例:可写做:
(KSFile*)pFile;
也可写做:
(KSFile *)pFile
不得写做:
( KSFile* )pFile
( KSFile * ) pFile
11. 与缩进有关的各项规定
11.1 缩进以 Tab 为单位。1 个 Tab 为 4 个空格
11.2 下列情况,代码缩进一个 Tab:
1. 函数体相对函数名及'{'、'}'。
例:
int Power(int x)
{
return (x * x);
} 2. if、else、for、while、do 等之后的代码。
3. 一行之内写不下,折行之后的代码,应在合理的位置进行折行。若有 + - * / 等运算符,则运算符应在上一行末尾,而不应在下一行的行首。
11.3 下列情况,不必缩进:switch 之后的 case、default。
例:
switch (nID)
{
case ID_PLAY:
break;
case ID_STOP:
break;
default:
break; 12.对于涉及到系统的功能调用,要求使用系统提供的宏,不得直接使用具体的数值。
例: char szSystemPath[MAX_PATH] = {0}; 正确
char szSystemPath[260] = {0}; 错误
13.关于函数编写的规定
13.1 除了非常简单的函数或者没有必要,函数需要有返回值,并且推荐
返回值的类型为int,成功时为 true,失败时为false。不推荐直接使用1和0来表示。
13.2 在函数内部变量定义全部放在函数的开始处,不能在代码中间出现 变量定义。变量定义需要初始化值,一般是0、false、NULL等。
13.3 程序员自行编写的函数不推荐使用DWORD等指明字节长度的变量 类型,推荐使用unsigned long等变量类型。对于ULONG等vc系统定义的变量类型,推荐使用unsigned long 来代替。如果调用系统API,在MSDN中已经指明了是DWORD等类型,则可以使用。
13.4 推荐使用int nResult作为函数自身的返回值变量,int nRetCode、BOOL bRetCode作为调用其他函数的返回值变量。
13.5 推荐使用goto语句来统一函数出口,goto语句一般只能跳转到一个函数出口,最多只能有两个,出口标识必须命名为Exit0和Exit1。在出口处必须显式检查曾经申请过的系统资源(如内存),并且进行释放。
13.6 如果编写DLL,除非特殊情况,导出函数的调用类型必须是__stdcall,便于多模块协同工作。
附录:
1.函数编写示范
/**////////////////////////////////////////////////////////////////////// //
// Remarks:
// Get file version information
//
// Parameters:
// [in] const char cszPathName : Input file path name
// [out] PVERSION_INFO *pVersionInfo : File version information
//
// Return values:
// int : Non-zero means success, zero means failure
//
/**////////////////////////////////////////////////////////////////////// int GetFileVersion(const char cszPathName, PVERSION_INFO *pVersionInfo)
{
int nResult = false;
int nRetCode = false;
char szSystemPath[MAX_PATH] = {0};
nRetCode = IsFileExist(cszPathname);
if (!nRetCode)
goto Exit0;
//Others code here
nResult = true;
Exit0:
return nResult;
}