干货 | Qt编程规范

王治钦

*编辑注：
文章作者：51CTO博客用户“mb5fd86853067b7”
文章链接：https://blog.51cto.com/u_15057811/4162882
一、概述

良好的编程规范可以大幅提高一个程序的可读性、可理解性和可维护性。
本规范参考Effective C++中文版、Google C++编码规范及Qt编码风格。


二、头文件

• #define保护
  所有头文件都应该使用#define防止头文件被多重包含，命名格式为：<ProjectName>_<FileName>_H，例如：
  #ifndef MAP_MAINWINDOW_H
  #define MAP_MAINWINDOW_H
  ……
  #endif //MAP_MAINWINDOW_H
  
• 头文件依赖
  使用前声明，尽量减少.h文件中#include的数量。
  
• 头文件包含次序
  

将包含次序标准化可增强可读性，次序如下：C库头文件、C++库头文件、其他库的头文件、项目内的头文件。
三、命名约定

• 通用命名约定
  避免使用缩写。
  
• 文件命名
  文件名全部小写，可以包含下划线，例如：
  my_test_class.h
  my_test_class.cpp
  mytestclass.h
  mytestclass.cpp
  
• 类命名
  类名是名词，每个单词以大写字母开头，不包含下划线，且名前加大写字母C，例如：
  CMySystemWatcher
  CClockBattery
  
• 变量命名
  变量名是名词，首单词以小写字母开头，后续单词以大写字母开头。每行一个变量，单字符的变量只在临时变量或循环计数中使用。
  类成员变量需在变量名前加m_前缀，例如：
  int m_myValue;
  局部变量等到需要使用时再定义变量，且定义时必须初始化，整数用0，实数用0.0，指针用NULL，字符（串）用'\0'。例如：
  int myValue=0;
  尽量不要使用全局变量，以降低耦合。若使用能带来极大便利，命名时需在变量前加g_前缀，例如：
  int g_myValue;
  
• 常量命名
  常量不含前缀且应该大写，单词间有下划线，包括全局常量和宏定义，例如：
  const int MY_VALUE=0;
  #define MY_VALUE 0
  
• 函数命名
  函数名是动词或含有动词的短语，首单词以小写字母开头，后续单词以大写字母开头，例如：
  int getMyValue();
  int setMyeValue(int value)
  函数参数所有字母小写，单词间有下划线，若为非基本数据类型，使用const引用，例如：
  setColor(const QColor & new_color)
  
• 枚举命名
  枚举名和枚举值都是名词，每个单词以大写字母开头，且第一个单词是Enum，例如：
  enum EnumMyColor //枚举名
  {
  EnumWhite,     //枚举值
  EnumBlack
  };
  
• 命名空间
  命名空间的名称是名词，每个单词以大写字母开头，且前两个单词是BaiDi，例如：
  namespace BaoDiProject{ }
  
• 结构体命名
  

结构体中只定义变量，不定义函数。
结构体名是名词，每个单词以大写字母开头。
结构体成员名词，首单词以小写字母开头，后续单词以大写字母开头。例如：
struct MyColor
{
    boolisMyColor;
    int white;
};


四、代码注释

• 注释风格
  使用//或/**/，统一就行。一般情况下，源程序有效注释量必须在20%以上，不易理解的地方都需加上注释，注释不宜太多也不能太少。
  
• 类注释
  类的头文件顶部需添加说明性注释，包括版权说明、版本号、作者、生成日期、类的功能描述等。
  /*****************************************************
  **Copyright(C), 2015-2025, Baodi Technology.
  **Version:
  **Author:            
  **Date:
  **Description://类用途描述     
  *****************************************************/
  
• 函数注释
  重要函数头部应该进行注释，包括函数名、函数功能描述、输入参数、输出参数、返回值及其他。
  /*************************************************
  **Function:        // 函数名称
  **Description:    // 函数功能描述
  **Input:          // 输入参数说明，包括每个参数的作用、取值说明
  **Output:         // 对输出参数的说明
  **Return:         // 函数返回值的说明
  **Others:         // 其它说明
  *************************************************/
  
• 变量注释
  通常变量名本身足以说明变量用途，特定情况下，需要额外注释说明。变量注释位于变量上方，例如：
  //keepstrack of the total number of entries in the table
  int  totalNumber;
  
• 实现注释
  对于实现代码中巧妙的、晦涩的、重要的地方加以注释。
  出彩或复杂的代码块上方要加以注释，例如：
  // Divide result by two, taking into account that x
  // contains the carry from the add.
  for(int i=0;i<100;i++)
  {
  x=(x<<8)+(*result);
  (*result)=x>>1;
  x&=1;
  }
  比较晦涩的地方可在行尾，代码之后空两格加注释，例如：
  if（……）
  {
      ……
     return;  //return while meetingthe conditions
  }
  
• TODO注释
  

计划中但未完成的代码使用TODO注释，例如：
void CMyClass::function()
{
    //TODO
}
五、代码排版

• 行长度
  较长的语句（>80字符）要分成多行书写，长表达式要在较低优先级操作符处划分新行，操作符放在新行之首，逗号放在一行的结束，划分出的新行要进行适当的缩进，使排版整齐，语句可读，例如：
  if ((taskOne < taskNumber)&&(taskTwo < taskNumber)
  &&(taskThree< taskNumber))
  {
           ……
  }
  
• 缩进
  使用4个空格进行代码缩进，不要用Tab键。但是对于由开发工具自动生成的代码可以有不一致。
  预处理指令不要缩进，从顶格开始，例如：
  if(isActive())
  {
  #if DISASTER_PENDING
      dropEverything();
  #endif
      backToNormal();
  }
  
• 空行
  空行可将语句进行适当的分组，便于阅读，在相对独立的代码块之间必须加一行空行。
  
• 大括号
  大括号永远单独占一行，不跟在语句后面。如果控制语句（if、while、for、switch）体为空或者只有一行，也要使用大括号，例如：
  if ( address.isEmpty( ) )
  {
  return false;
  }
  switch(value)
  {
      case 0:
  {
      get Electricity();
      break;
  }
  default:
  {
       break;
  }
  }
  
• 圆括号
  

使用圆括号将表达式分组，即使运算符的优先级相同，也要用圆括号进行分组，例如：
if ( ( a && b) | | c)
六、重要原则

正确性>稳定性>可测试性>可读性>全局效率>局部效率>个人习惯

• 正确性，指程序要实现设计要求的功能；
  
• 稳定性、安全性，指程序稳定、可靠、安全；
  
• 可测试性，指程序要具有良好的可测试性；
  
• 规范/可读性，指程序书写风格、命名规则等要符合规范；
  
• 全局效率，指软件系统的整体效率；
  
• 局部效率，指某个模块/子模块/函数的本身效率；
  
• 个人表达方式/个人方便性，指个人编程习惯。