编程风格要求总结

程序设计风格要求总结

排版
1、程序块要采用缩进风格编写 ，缩进的空格数为 4 个。 原因说明： 由开发工具自动生成的代码可能不一致，但如果开发工具可以配置，则应该统一配 置缩进为 4 个空格。
2、缩进或者对齐只能使用空格键 ，不可使用 TAB 键。说明 ： 使用 TAB 键需要设置 TAB 键的空格数目是 4 格。
3、相对独立的程序块之间，变量说明之后必须加空行。 说明 ： 以下情况应该是用空行分开：
1）函数之间应该用空行分开；
2）变量声明应尽可能靠近第一次使用处，避免一次性声明一组没有马上使用的变量；
3）用空行将代码按照逻辑片断划分；
4）每个类声明之后应该加入空格同其他代码分开。
4、 较长的语句（>80 字符）要分成多行书写。
1）长表达式要在低优先级操作符处划分新行，操作符放在新行之首，划分出的新行 要进行适当的缩进，使排版整齐，语句可读。
2）若函数或过程中的参数较长，则要进行适当的划分。
3）循环、判断等语句中若有较长的表达式或语句，则要进行适应的划分，长表达式 要在低优先级操作符处划分新行，操作符放在新行之首。
5、不允许把多个短语句写在一行中，即一行只写一条语句。 说明： 一行代码只做一件事情，如只定义一个变量，或只写一条语句。这样的代码容易阅 读，并且方便于写注释。
6、if、for、do、while、case、switch、default default default 等语句自占一行 等语句自占一行，且 if、for、 do、while 等语句的执行语句部分无论多少都要加括号，等语句的执行语句部分无论多少都要加括号{}。
7、代码行之内应该留有适当的空格。说明：采用这种松散方式编写代码的目的是使代码更加清晰。
1）关键字之后要留空格。象 const、virtual、inline、case 等关键字之后至少要留一 个空格， 否则无法辨析关键字。象 if、for、while 等关键字之后应留一个空格再跟左 括号‘（ ’， 以突出关键字。
2）函数名之后不要留空格， 紧跟左括号’(’ ， 以与关键字区别。
3）‘( ’ 向后紧跟，‘ )’、‘ ，’、‘ ;’ 向前紧跟， 紧跟处不留空格。
4）值操作符、比较操作符、算术操作符、逻辑操作符、位域操作符，如“ =”、“ +=” “ >=”、“ <=”、“ +”、“ *”、“ %”、“ &&”、“ ||”、“ <<” 、“ ^” 等二元操作符 的前后应当加空格。
5）一元操作符如“ !”、“ ~”、“ ++”、“ –”、“ &”（ 地址运算符） 等前后不加 空格。 7）象“［ ］”、“ .”、“ ->” 这类操作符前后不加空格。

注释
1、源文件头部应进行注释，列出：生成日期、作者、模块目的/功能等。
2、函数头部应进行注释，列出：函数的目的/功能、输入参数、输出参数、返回 值等。
3、注释应该和代码同时更新 ，不再有用的注释要删除。
4、注释的内容要清楚，不能有二义性。 说明： 错误的注释不但无益反而有害。
5、避免在注释中使用非常 ：避免在注释中使用非常用的缩写或者术语。
6、注释的主要目的应该是解释为什么这么做，而不是正在做什么。如果从上下 文不容易看出作者的目的，说明程序的可读性本身存在比较大的问题 ，应考虑对其重构。
7、避免非必要的注释
8、注释的版式 说明：注释也需要与代码一样整齐排版 。
1）注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开。
2）注释与所描述内容进行同样的缩排。
3）将注释与其上面的代码用空行隔开。
4）变量、常量、宏的注释应放在其上方相邻位置或右方。
9、对于所有有物理含义的变量，如果其命名不是充分自注释的，在声明 时都必须加以注释，说明其物理含义。
10、数据结构声明(包括数组、结构、类、枚举等)，如果其命名不是充分自注释，必须加以注释。对数据结构的注释应放在其上方相邻位置 ，不可放在下面；对结构中的每个域的注释可放在此域的右方。
11、对重要变量的定义需编写注释 ，特别是全局变量，更应有较详细的注释，包 括对其功能、取值范围、以及存取时注意事项等的说明 、以及存取时注意事项等的说明。
12、分支语句（条件分支、循环语句等）需编写注释。 说明： 这些语句往往是程序实现某一特定功能的关键，对于维护人员来说，良好的注释帮助更好的理解程序，有时甚至优于看设计文档。
13、 注释不宜过多 也不能太少，源程序中有效注释量控制在 20％~30%之间。 说明： 注释是对代码的“提示”，而不是文档，不可喧宾夺主，注释太多会让人眼花缭乱。
命名
1、命名尽量使用英文单词 ：力求简单清楚 ，避免使用引起误解的词汇和模糊的 ，使人产生误解。 说明： 较短的单词可通过去掉“元音”形成缩写；较长的单词可取单词的头几个字母形成缩写；一些单词有大家公认的缩写。
2、命名规范必须与所使用的系统风格保持一致，并在同一项目中统一 ，并在同一项目中统一。 说明
1）如在 UNIX 系统，可采用全小写加下划线的风格或大小写混排的方式，但不能使 用大小写与下划线混排的方式。
2）用作特殊标识如标识成员变量或全局变量的 m_和 g_，其后加上大小写混排的方 式是允许的。
3、常量、宏和模板名采用全大写的方式 、宏和模板名采用全大写的方式，每个单词间用下划线分隔。
4、枚举类型 enum 常量应以大写字母开头或全部大写 enum 常量应以大写字母开头或全部大写。
5、命名中若使用了特殊约定或缩写，则要有注释说明。 说明： 应该在源文件的开始之处，对文件中所使用的缩写或约定，特别是特殊的缩写，进 行必要的注释说明。
6、自己特有的命名风格，要自始至终保持一致，不可来回变化。
8、函数名以大写字母开头，采用谓-宾结构（动-名），且应反映函数执行什么 操作以及返回什么内容。
可读性
1、用括号明确表达式的操作顺序 ，避免使用默认优先级。
2、不要编写太复杂、多用途的复合表达式。
3、涉及物理状态或者含有物理意义的常量 ，避免直接使用数字，必须用有意义的枚举或常量来代替。
4、禁止使用难以理解，容易产生歧义的语句。

C++专用规范
1、在高警告级别下干净地编译。 使用编译器的最高警告级别。要求干净的（没有警告的）构建（build）并理解所有 的警告。通过修改代码来消除警告，而不是通过降低警告级别来消除。对于明确理解其 含义，确信不会造成任何问题的警告，则可以局部关闭。
2、确保资源为对象所占有，使用显式的 RAII 和智能指针 RAII 和智能指针。
3、主动使用 const，避免使用宏。 应该尽可能的使用常量而不用变量，另外在定义数值的时候，应该把 const 做为默 认的选项。
4、合理使用组合(composition)和继承 (composition)。 继承是 C++中耦合度最强的关系之一。软件工程的一条重要原则是尽量减少耦合，在 组合和继承都能均可适用的情况下，应该优先考虑使用组合。组合的意思是将一种类型 以成员变量方式嵌入相关类型中。组合有如下优点：
1）在不影响调用代码的同时也更灵活。
2）编译期绝缘性好，编译时间也能缩短。
3）代码不可预测程度降低（有些类不适合作为基类）。
5、尽可能局部地声明变量，这通常是在程序具备了足够的数据来初始化变量之后， 并紧接着首次使用该变量之前。 例外：
1）有时将变量从循环内提出到循环外是有益的。
2）由于常量不增加状态，因此本条对常量不适用。
6、尽量用异常来报告错误。与错误码相比，要尽量用异常来报告错误。对一些无法使用异常的错误，或者一些不属于错误的情况，可以用状态码（status code，例如：返回码，errno）来报告。如果不可能或不需要从错误中恢复，那么可以使用其它方法，比如正常或非正常地终止程序。在 C++中，和用错误码来报告错误相比，用异常来报告错误具有许多明显的优势，所有这些都使得编出来的代码更健壮：
1）程序员不能无视异常：错误码的最糟糕的缺点就是在默认情况下它们会被忽略； 即使是给予错误码微不足道的关注，都必须显式地编写代码，以接受错误并做出反应。程序员因为偶然（或因为懒惰）而忘记关注错误码是很平常的事。这使得代码复查变得更困难。
2）异常会自动传递：默认情况下错误码不会跨作用域传递；为了把一个低层的错误 码通知高层的调用函数，程序员必须在中间层的代码中显式地手工编写代码以传递 该错误。异常会自动地跨作用域传递，直到被处理为止。
3）异常处理从主控制流中去除了错误处理及恢复：错误码的检测及处理，一旦要写的话，就必须夹杂在主控制流中（并使之变得难以理解）。这使得主控制流以及错误 处理的代码都更难以理解和维护。异常处理很自然地把错误检测及恢复移到醒目的 catch 代码块中，即它使错误处理既醒目，又易于使用，而不是纠缠在主控制流中。

个人编码模板
1、代码的可读性要高
对函数和变量的命名应有意义，注释的表达应该简洁而准确。
2、 遵循正确的命名约定
当需要给类、函数和变量命名时，需要遵循以下几点：
1)、确保特定类名的第一个字母大写；
2)、使用大小写分离多个单词的命名；
3)、大写常数名，并使用下划线分离单词；
4)、确保特定功能和变量名的第一个字母小写；
5)、注意正确使用缩写。例如，用max而不用maximum。
3、必要时可使用空格
虽然空格对编译器是没有意义的，但是可用于提高代码的可读性。。
4、注释必须易于理解
在每个源文件的顶部，使用/* */的风格来写多行注释，在注释中包括名字，编写代码的日期，以及简明扼要地说明程序的实际用途。单行注释采用//进行注释
5、整体的代码缩进
保证缩进的空格数为4，在缩进和对齐时使用空格键，或者使用已经设置好空格数为4的 TAB键（未设置的TAB键不使用）。