初级c++编码规范

    想了很久，第一篇文章还是应该写编码规范好一点。编码规范是一个仁者见仁的问题，为了避免复杂庞大，自己总结了一套简单版本的规范。

简介

    本文介绍一份自己使用的C++编码规范。第一次正式进入软件行业（第一份工作）是13年，经过这些年的磕磕碰碰，现在深刻认同编码规范的重要性。本文总结的是自己使用的编码规范中的命名规范，该规范主要来自于”google的开源代码编码规范“，少数几个地方根据自己的理解进行了调整。

注释

    文件头注释示例：

/*************************************************
* Copyright (c) 2016, Zhangping.
* All rights reserved.
*
* Author:why
* E-mail：bluepc_2013@163.com
* Date  :2016-08-25
* Brief :Something about C++
**************************************************/  

    其中，表示版权起始日期是2016年，版权所有者是zhangping。对于一个公司，其声明格式为“Copyright (c) 2016, Zhangping, Inc.” 后面的"Inc"是公司的缩写。

    函数头部注释示例:

/*************************************************
* Function:       // 函数名称
* Brief:          // 函数功能、性能等的描述
* Calls:          // 可选,被本函数调用的函数清单
* Table Accessed: // 可选,被访问的表(此项仅对于牵扯到数据库操作的程序)
* Table Updated:  // 可选,被修改的表(此项仅对于牵扯到数据库操作的程序)
* Input:          // 输入参数说明,包括每个参数的作
*                 // 用、取值说明及参数间关系。
* Output:         // 对输出参数的说明,这里的输出参数包括一些用于输出计算
*                 // 结果的形参。
* Return:         // 函数返回值的说明
* Others:         // 其它说明
*************************************************/

    其他地方(例如:类)也采用相似的方式来添加注释,但应该简单明了。

字符串分行

    一行代码的长度不应该超过80个字符。对于长字符串,下面示例了两种分行方法,

#include <iostream>
int main(){
  // Method 1:
  //     a).'\'贴着最后一个字符
  //     b).第二行不能有空格或Tab
  std::cout<<"aaaaaaaa\
aa"<<std::endl;
  // Method 2:
  std::cout<<"bbbbbb"
    "bbbbbbb"<<std::endl;
  return 0;
}

    个人推荐第二种，因为第一种使代码排版变得不工整。

头文件的#define保护

    定义名应该采用“工程名 + 路径 + 文件名”的组合方式，且尽量使用全称。下面是一个头文件保护的示例,

#ifndef PROJECT_PATH_FILE_H_
#define PROJECT_PATH_FILE_H_
    ...
#endif

文件命名

    文件名要全部小写,可以包含下划线(_)。例如:imu_device.cc。c++源文件要以 “.cc” 结尾,头文件以".h"结尾。

类型命名

    所有类型命名­­类,结构体,类型定义(typedef),枚举,类型模板参数­­均使用相同约定。以大写字母开始,每个单词首字母均大写(仅仅首字母大写,例如:DNS应该写为Dns),不包含下划线。示例如下:

// 类和结构体
class UrlTable {...}
class UrlTableTester {...}
struct UrlTableProperties {...}
// 类型定义
typedef hash_map<UrlTableProperties *, string> PropertiesMap;
// Using 别名
using PropertiesMap = hash_map<UrlTableProperties *, string>
// 枚举
enum UrlTableErrors {...}

变量命名

    变量(包括:局部变量,函数形参)和数据成员名一律小写,单词之间用下划线连接。类的成员变量以下划线结尾。结构体的成员变量不要用下划线结尾。示例如下,

// 普通变量
string table_name // 用下划线分割
// 类数据成员
class TableInfo {
  ...
  private:
    string table_name_; // 用下划线结尾
    static string table_name2_; // 静态成员变量依然下划线结尾
};
// 结构体数据成员
struct TableInfo{
    string table_name;         // 命名方式同普通变量
    static string table_name2;
};

    这种命名方式能带来一些便利。例如:写了一个类QueryResult后,可以直接定义一个变量query_result,区分度是很好的;另外,类内变量以下划线结尾,那么就可以直接传入同名的形参,使用起来简单明了。

常量命名

    声明为constexpr或const的变量,命名时以"k"开头,大小写混合。例如:

const int kDaysInAWeek = 7;

    这种明显差异于普通变量的命名方式,用以提醒阅读者该变量是一个常量。

静态变量

    声明在局部范围(例如:函数内)的静态变量,命名时以"s"开头,大小写混合。例如:

void fun(){
    ...
    static int sDayInAWeek = 7;
}

    看到该标志,应该立刻注意到该变量能记忆上次调用的值。

全局变量

    全局变量命名时以"g"开头,大小写混合。如果一个变量即是全局变量,也是static类型,则此时也应该使用"g"开头。因为全局变量标志比静态变量标志提供了更多的信息(具体原因见下面的说明)。示例,

i   nt gDayInAWeek = 7;
static int gDayInAWeek = 7;
...
int main(){
    ...
}

    看到"g"标志,应该立刻注意到该变量来自这个程序片的外部,该变量除了在当前程序片上被修改(即记忆上次调用的值),还可能在其他地方被修改。这也是为什么静态全局变量使用标识"g"的原因。

函数命名

    常规函数使用大小写混合,取值和设值函数则采用与普通变量名一致的命名规则。例如:

// 常规函数
void MyFunction();
// 取值和设值函数
int get_my_variable();
void set_my_variable(int);

    这个差异一方面是为了美观,另一方面也能提醒读者函数的差异。常规函数内部包含一定的程序逻辑,而取值和设值函数则没有。一般来说,只有成员变量会有取值和设值函数,所以采用了近似于成员变量的命名方式。如果需要为全局变量设置这两个函数时,也可以采用这种命名方式。因为只有需要借用外部文件的全局变量时才会设置这两个函数,此时是没有必要区分是否是全局变量的(如果采用全局变量的命名方式来命名这两个函数,反而容易引起其他麻烦)。

命名空间命名

    命名空间以小写字母命名,以下划线分割(类似于普通变量命名)。尽量不要缩写,因为缩写可能导致与其他库(或代码)的命名空间重名,而且命名空间中的代码极少需要涉及命名空间的名称,因此没有必要使用缩写。示例如下,

namespace my_name_space{
    ...
}

枚举命名

    枚举类型采用类class的方式命名(首字母大写,大小写混合) ,枚举值采用常量的方式命名(k开头,后面大小写混合)。示例如下,

/* 枚举类型示例 */
enum ErrorTypes{
  kOK = 0,
  kErrorOutOfMemory,
  kErrorOther,
};
int main(){
  ErrorTypes type = kOK
  type = kErrorOther;
  return 0;
}

    枚举值与常量的使用方式和特性相似,所以采用相同的命名方式。另外,也考虑过将枚举值采用“全大写,下划线分割”的方式命名,但那种命名方式有可能与宏冲突,所以放弃。

宏命名

    宏应该尽量少用,一般可以用常量替代。如果确实要使用,建议采用“全大写,下划线”分割的方式命名。示例如下,

#define PI_ROUNDED 3.0

Reference

    [1] http://zh­google­styleguide.readthedocs.io/en/latest/ 这里是google建议的编码规范,包含C++,python,shell,objective­c

    [2] https://blog.csdn.net/pleasecallmewhy/article/details/8658795 C++注释的规范参考了这里