01软件编码和命名规范课件.docx
- 文档编号:24368635
- 上传时间:2023-05-26
- 格式:DOCX
- 页数:13
- 大小:21.06KB
01软件编码和命名规范课件.docx
《01软件编码和命名规范课件.docx》由会员分享,可在线阅读,更多相关《01软件编码和命名规范课件.docx(13页珍藏版)》请在冰豆网上搜索。
01软件编码和命名规范课件
项目编号:
AN_DX_012
第三届中国大学生服务外包创新应用大赛
盐城师范学院参赛团队(ITGroup)
下位机软件编码和命名规范
2012.7
文档修订记录
版本
完成人
修改内容
审核
批准
时间
V1.0
徐裕峰
创建文档
全体
2012-6-3
1注释常用标签说明
@author
表示作者信息
@brief
用于function的批注中,后面为function的简易说明。
@param
格式为
@param[in,intout,out]arg_name-参数说明
主要用于函数说明中,后面接参数的名字,然后再接关于该参数的说明。
@return
后面接函数传回值的说明。
用于function的批注中。
说明该函数的传回值。
@Revision
用于说明文件版本号
@Revised
用于说明修改内容、时间和修改者
格式为
20xx.x.x(XXX对XXXX进行修改)
2注释规范
2.1注释原则
有助于对程序的阅读理解,说明程序在"做什么",解释代码的目的、功能和采用的方法。
一般情况源程序有效注释量在50%左右。
注释语言必须准确、易懂、简洁。
边写代码边注释,修改代码同时修改相应的注释,不再有用的注释要删除。
2.2源文件头部注释规范
文件注释必须说明文件名、函数功能、创建人、创建日期、版本信息等相关信息。
修改文件代码时,应在文件注释中记录修改日期、修改人员,并简要说明此次修改的目的。
所有修改记录必须保持完整。
文件注释放在文件顶端,用"/*……*/"格式包含。
注释文本每行缩进一个制表符;每个注释文本分项名称应对齐。
:
/***********************************************************
*@FilenameSHT1X.c
*@authorXXXX
*@Revision:
V1.0
@Revised:
2012.7.22(XXX改XXX)
*@brief:
SHT1X系列芯片驱动文件
***********************************************************/
2.3数据变量注释
同一类型的标识符应集中定义,并在定义之前一行对其共性加以统一注释。
对单个标识符的注释加在定义语句的行尾。
全局变量一定要有详细的注释,包括其功能、取值范围、哪些函数或过程存取它以及存取时的注意事项等。
注释用"//…"的格式。
2.4函数注释
函数头部注释应包括函数名称(@fu)、函数描述(@brief)、入口参数(@param)、出口参数(@return)等内容。
如有必要还可增加作者、创建日期、修改记录(备注)等相关项目。
函数头部注释放在每个函数的顶端,用"/*……*/"的格式包含。
其中函数名称应简写为FunctionName,不加入、出口参数等信息。
/***********************************************************
*@fnMT_AfDataConfirm
*
*@briefAD数据处理过程
*
*@parampBuf–指向接收数据缓冲区物理地址的指针
*
*@returnvoid
***********************************************************/
voidMT_AfDataConfirm(afDataConfirm_t*pMsg)
{
uint8retArray[3];
retArray[0]=pMsg->hdr.status;
retArray[1]=pMsg->endpoint;
retArray[2]=pMsg->transID;
/*创建和回传信息*/
MT_BuildAndSendZToolResponse(((uint8)MT_RPC_CMD_AREQ|(uint8)MT_RPC_SYS_AF),MT_AF_DATA_CONFIRM,3,retArray);
}
2.4.1无参数型注释
文档注释描述C,方法,以及字段(field)。
每个文档注释都会被置于注释定界符/*...*/之中,一个注释对应一个成员或方法。
该注释应位于声明之前:
/***********************************************************
*@fnMT_Init
*
*@briefInitializeMT.
*
*@returnvoid
***********************************************************/
voidMT_Init()
{
debugThreshold=0;
debugCompId=0;
#ifdefined(MT_ZDO_FUNC)
MT_ZdoInit();
#endif
MT_SysResetInd();
}
2.4.2void型
/***********************************************************
*@fnMT_Init
*
*@brief用于初始化MT
*
*@paramuint8taskId–一个ID标识
*
*@returnvoid
***********************************************************/
voidMT_Init(uint8taskID)
{
MT_TaskID=taskID;
debugThreshold=0;
debugCompId=0;
#ifdefined(MT_ZDO_FUNC)
MT_ZdoInit();
#endif
MT_SysResetInd();
}
4个空格常被作为缩进排版的一个单位。
缩进的确切解释并未详细指定(空格vs.制表符)。
一个制表符等于8个空格(而非4个)。
2.5结构体注释
/***********************************************************
*@brief用于存取数据结构体
*
*@paramintcount–记数用
*
*@paramcharsData–存数数据
***********************************************************/
structpoint
{
//包含两个变量成员
int count;
charsData;
};
2.6枚举类型注释
/***********************************************************
*@brief用于列举数据图类型
*
*@paramELine
*
*@paramEBar
*
*@paramEPie
*
*@paramEArea
***********************************************************/
enumChartType
{
ELine=0,//直线图
EBar,//条形图
EPie,//饼图
EArea,//面积图
…
};
2.7共用体注释
/***********************************************************
*@brief定义公用体CellValue用于数据存储
*
*@paramintiVal–存储数据
*
*@param*pszVal–存储数据地址
*
*@paramdVal–存储数据
***********************************************************/
unionCellValue
{
intiVal;
char*pszVal;
doubledVal;
};
2.8TODO注释
对那些临时的,短期的解决方案,或已经够好但仍不完美的代码使用 TODO 注释。
TODO 注释要使用全大写的字符串 TODO,在随后的圆括号里写上你的大名,邮件地址,或其它身份标识。
冒号是可选的。
主要目的是让添加注释的人(也是可以请求提供更多细节的人)可根据规范的 TODO 格式进行查找。
添加 TODO 注释并不意味着你要自己来修正。
//TODO(kl@):
Usea"*"hereforconcatenationoperator.
//TODO(Zeke)changethistouserelations.
如果加 TODO 是为了在“将来某一天做某事”,可以附上一个非常明确的时间“FixbyNovember2005”),或者一个明确的事项(“RemovethiscodewhenallclientscanhandleXMLresponses.”)。
3命名规范
3.1命名基本原则
命名要清晰明了,有明确含义,使用完整单词或约定俗成的缩写。
通常,较短的单词可通过去掉元音字母形成缩写;较长的单词可取单词的头几个字母形成缩写。
即"见名知意"。
命名风格要自始至终保持一致。
命名中若使用特殊约定或缩写,要有注释说明。
除了编译开关/头文件等特殊应用,应避免使用以下划线开始和/或结尾的定义。
同一软件产品内模块之间接口部分的标识符名称之前加上模块标识。
3.2文件命名
一个文件包含一类功能或一个模块的所有函数,文件名称应清楚表明其功能或性质。
每个.c文件应该有一个同名的.h文件作为头文件。
3.3数据变量命名
变量名用小写字母命名,每个词的第一个字母大写。
类型前缀(u8\s8etc.)全局变量另加前缀g_。
局部变量应简明扼要。
局部循环体控制变量优先使用i、j、k等;局部长度变量优先使用len、num等;临时中间变量优先使用temp、tmp等。
。
例:
stringm_strName;
intiLength;
usignedintnSize;
3.4宏和常量命名
宏和常量用全部大写字母来命名,词与词之间用下划线分隔。
对程序中用到的数字均应用有意义的枚举或宏来代替。
3.5函数命名
函数名用小写字母命名,每个词的第一个字母大写,并将模块标识加在最前面。
例:
StirnggetParameters();
3.6结构体命名
结构体以tag开头,之后可用typedef重新定义别名。
例:
structtagChartBoxplotData
{
stringstrName;//类轴
doubledQ1;//第25个百分位数
doubledQ2;//第50个百分位数
};
3.7枚举命名
枚举类型命名成员用E开头,如ELine。
例:
enumChartType
{
ELine=0,//直线图
EBar,//条形图
EPie,//饼图
EArea,//面积图
};
3.8共用体命名
typedefunion
{
unsignedinti;//定义了两个共用体
floatf;
}valuen;
4排版规范
4.1缩进
代码的每一级均往右缩进一个制表符Tab的位置。
If()
{
If()
{
}
}
4.2分行
过长的语句(超过80个字符)要分成多行书写;长表达式要在低优先级操作符处划分新行,操作符放在新行之首,划分出的新行要缩进一个制表符,使排版整齐,语句可读。
避免把注释插入分行中。
4.3空行
文件注释区、头文件引用区、函数间应该有且只有一行空行。
相邻函数之间应该有且只有一行空行。
函数体内相对独立的程序块之间可以用一行空行或注释来分隔。
函数注释和对应的函数体之间不应该有空行。
文件末尾有且只有一行空行。
4.4空格
函数语句尾部或者注释之后不能有空格。
括号内侧(即左括号后面和右括号前面)不加空格,多重括号间不加空格。
函数形参之间应该有且只有一个空格(形参逗号后面加空格)。
同一行中定义的多个变量间应该有且只有一个空格(变量逗号后面加空格)。
表达式中,若有多个操作符连写的情况,应使用空格对它们分隔:
在两个以上的关键字、变量、常量进行对等操作时,它们之间的操作符前后均加一个空格;在两个以上的关键字、变量、常量进行非对等操作时,其前后均不应加空格;逗号只在后面加空格;双目操作符,如比较操作符,赋值操作符"="、"+=",算术操作符"+"、"%",逻辑操作符"&&"、"&",位操作符"<<"、"^"等,前后均加一个空格;单目操作符,如"!
"、"~"、"++"、"-"、"&"(地址运算符)等,前后不加空格;"->"、"。
"前后不加空格;if、for、while、switch等关键字与后面的括号间加一个空格。
4.5switch语句
每个case和其判据条件独占一行。
每个case程序块需用break结束。
特殊情况下需要从一个case块顺序执行到下一个case块的时候除外,但需要在交界处明确注释如此操作的原因,以防止出错。
case程序块之间空一行,且只空一行。
每个case程序块的执行语句保持一个制表符的缩进。
一般情况下都应该包含default分支。
Switch()
{
casex:
break;
casex:
break;
default:
break;
}
5附录
常用类型所对应缩写表:
常用前缀缩写:
类型
缩写
示例
BOOL
b
bEnable
char
ch
chText
Handle(句柄)
h
hWnd
Int
i
iLength
无符号整型(unsignedint)
n
nSize
指针
p
pName
字符串
sz,str
strBuffer,szBuffer
WORD
w
坐标
x,y
float
f
fVal
double
d
dVal
long
l
lLength
非常用前缀:
Int类型nCmdShow;
LONG类型lParam;
UINT类型uNotify;
DWORD类型dwStart;
PSTR类型pszTip;
LPSTR类型lpCmdLine
LPTSTR类型lpszClassName;
LPVOID类型lpReserved
WPARAM类型wParam,
LPARAM类型lParam
HWND类型hDlg;
HDC类型hDC;
HANDLE类型hInstance,
HICON类型hIcon;
DWORDdw*
g_全局变量g_nMsg,g_bFlag
局部变量中可采用如下几个通用变量:
nTemp,nResult,I,J(一般用于循环变量)。
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 01 软件 编码 命名 规范 课件