文档介绍：最全面的C C++编码规范总结
对于不同的编程语言来说,具体的编码规范可以有很大的不同,但是其宗旨都是一致的,就是保证代码在高质量完成需求的同时具备良好的可读性、可维护性。例如我们可以规定某个项目的C语言程序要遵循这样的规定:变量的命名,头文件的书写和#include 等等。
下面是一些广为采用的编码规范:
GNU Coding Standards
Guidelines for the Use of the C Language in Vehicle Based Software
C++ Coding Guidelines
SUN Code Conventions for Java
以下是一些介绍编码、编码规范的书籍:
C++编码规范,陈世忠,人民邮电出版社,2002
高质量程序设计指南:C++/C语言,林锐等,电子工业出版社,2003
注:以下只是根据课题组已有的经验给出的总结,并非对所有场景均适用。
对于高质量的工程,一般会做到:
代码简洁精炼,美观,可读性好,高效率,高复用,可移植性好,高内聚,低耦合,没有冗余,不符合这些原则,必须特别说明。
规范性,代码有规可循。特殊排版、特殊语法、特殊指令,必须特别说明。
一、文件排版方面
先系统头文件,后用户头文件。
系统头文件,稳定的目录结构,应采用包含子路径方式。
自定义头文件,不稳定目录结构,应在dsp中指定包含路径。
系统头文件应用:#include <>
自定义同文件应用:#include ""
只引用需要的头文件。
头文件命名为*.h,内联文件命名为*.inl;C++文件命名为*.cpp
文件名用大小写混合,或者小写混合。,。不要用无意义的名称:;;;
头文件除了特殊情况,应使用#ifdef控制块。
头文件#endif应采用行尾注释。
头文件,首先是包含代码块,其次是宏定义代码块,然后是全局变量,全局常量,类型定义,类定义,内联部分。
CPP文件,包含指令,宏定义,全局变量,函数定义。
文件应包含文件头注释和内容。
函数体类体之间原则上用2个空行,特殊情况下可用一个或者不需要空行。
文件头、控制块,#include部分、宏定义部分、class部分、全局常量部分、全局变量部分、函数和函数之间,用两个空行。
二、注释方面
作者,文件名称,文件说明,生成日期(可选)
关键函数必须写上注释,说明函数的用途。
特别函数参数,需要说明参数的目的,由谁负责释放等等。
除了特别情况,注释写在代码之前,不要放到代码行之后。
对每个#else或#endif给出行末注释。
关键代码注释,包括但不限于:赋值,函数调用,表达式,分支等等。
善未实现完整的代码,或者需要进一步优化的代码,应加上 // TODO ...
调试的代码,加上注释 // only for DEBUG
需要引起关注的代码,加上注释 // NOTE ...
对于较大的代码块结尾,如for,while,do等,可加上 // end for|while|do
三、命名方面
同一性:在编写一个子模块或派生类的时候,要遵循其基类或整体模块的命名风格,保持命名风格在整个模块中的同一性。
标识符组成:标识符采用英文单词或其组合,应当直观且可以拼读,可望文知意,用词应当准确,避免用拼音命名。
最小化长度&& 最大化信息量原则:在保持一个标识符意思明确的同时,应当尽量缩短其长度。
避免过于相似:不要出现仅靠大小写区分的相似的标识符,例如"i"与"I","function"与"Function"等等。
避免在不同级别的作用域中重名:程序中不要出现名字完全相同的局部变量和全局变量,尽管两者的作用域不同而不会发生语法错误,但容易使人误解。
正确命名具有互斥意义的标识符:用正确的反义词组命名具有互斥意义的标识符,如:"nMinValue" 和 "nMaxValue","GetName()" 和"SetName()" ….
避免名字中出现数字编号:尽量避免名字中出现数字编号,如Value1,Value2等,除非逻辑上的确需要编号。这是为了防止程序员偷懒,不肯为命