摘要

C++代码风格、优雅、静态代码检查工具、注释

介绍

内容

注释

注释风格

原则：统一
使用//或/* */，一般//更常用

文件注释

在每一个文件开头加入版权、作者、时间、法律公告、许可证版本等描述。

函数注释

函数声明处的注释描述函数功能;
定义处的注释描述函数实现：编程技巧、大致步骤、编程原由等

变量注释

一般变量名已标识用途，仅添加额外特殊说明

拼写注释

变量/函数命名过长时

TODO注释

临时、短期的解决方案，不完美代码等
全大写TODO
圆括号内提供身份标识内容：(name\email\bugID\issue)

命名

开发原则

  • 保持简单和直接原则(KISS, Keep it simple and stupid)：保持代码尽可能简单，如果需求需要的话，才在代码中引入灵活的可变点，只添加那些可使整体变得更简单的局部复杂的东西。
  • 不需要原则(YAGNI, You’re not gonna need it)：总是在你真正需要的时候再实现他们，而不是在你只是预见到你将来会需要他们而去实现，在真正需要的时候再写代码，那时再重构也来得及。
  • 避免复制原则(DRY, Do not repeat yourself)：不要复制，不要重复，这是相当危险的操作，你修改一处代码的时候总能记得去修改另外一处或另外多处你曾经复制的代码吗？
  • 信息隐藏原则：一段代码调用了另外一段代码，调用者不应该知道被调用者代码的实现，否则调用者就有可能修改被调用者的实现来实现某些功能，而这有可能引发其它调用者的bug。
  • 高内聚低耦合原则：类似单一职责原则，明确每个模块的具体责任，尽量少的依赖于其它模块。
  • 最少惊讶原则：函数功能要与函数名字功能一致，难道你要在一个getter()函数去更改成员变量的值吗？
  • 更干净原则(自命名)：当发现代码中有需要改进或者风格不好的地方，应该立刻改掉，不要care这段代码的原作者是谁，也不要care这是谁的模块，代码所有权是集体的，每个团队成员在任何时候都应该可以对任何代码进行更改和扩展

命名规则

良好命名，通过函数的名字我们就可以知道这个函数里代码的作用，而不是通过写注释宁可长也要有意义、尽量不要用缩写、可用常见for i、tmp。

一个变量尽量在临近使用前才定义，可读性强也可更好利用cpucache

文件命名

全部小写，中间用_相连，后缀名为.cc和.h

类型命名

每个单词首字母均大写, 不包含下划线: MyExcitingClass,MyExcitingEnum

变量命名

不要将变量的类型在名字中体现（充分利用IDE的功能）、
变量 (包括函数参数) 和数据成员名一律小写, 单词之间用下划线连接
类的成员变量以下划线结尾, 但结构体的就不用

常量/枚举命名

声明为constexpr 或 const 的变量, 或在程序运行期间其值始终保持不变的, 命名时以 “k” 开头, 大小写混合

全局变量

“g” 开头, 大小写混合

函数命名

常规函数使用大小写混合, 取值和设值函数则要求与变量名匹配 val() setVal()

注释风格

编程 | C/C++代码规范注释 - 知乎 (zhihu.com)

Doxygen快速入门 - 知乎 (zhihu.com)

代码注释规范之Doxygen - silencehuan - 博客园 (cnblogs.com)

Vs code自动生成Doxygen格式注释 - silencehuan - 博客园 (cnblogs.com)

doxygen的基本标注规则及实例_oxidane-lin的博客-CSDN博客

doxygen 注释规范_AlexBein的博客-CSDN博客_doxygen注释规范

最佳实践：功能注释在C / C ++代码中应该放在哪里？ - 问答 - 云+社区 - 腾讯云 (tencent.com)

代码整洁（2）：函数、注释 - BNDong - 博客园 (cnblogs.com)

Doxygen给C程序生成注释文档 - on_the_road - 博客园 (cnblogs.com)

基于 Doxygen 的C语言简要注释规范 - Linger 的博客 (liuguogy.com)

Doxygen 注释语法和使用_黎国溥-CSDN博客

C语言中的Doxygen注释模板_胡图图-CSDN博客_c语言函数注释模板

【工具篇】把代码注释生成技术文档 - 知乎 (zhihu.com)

Doxygen: Doxygen

其他

  • 每个头文件都要使用#define避免被重复引用（或使用#pragma once，而#define方式更通用）
  • 命名格式 H
  • 鼓励在 .cc 文件内使用匿名命名空间或 static 声明. 使用具名的命名空间时, 其名称可基于项目名或相对路径. 禁止使用 using 指示， 禁止使用内联命名空间（inline namespace）
  • 所有的引用形参如不做改动一律加const，在任何可能的情况下都要使用 const或constexpr
  • new内存的地方尽量使用智能指针，c++11 就尽量用std::unique_ptr替代std::auto_ptr
  • 合理使用移动语义，减少内存拷贝，参考左值引用、右值引用、移动语义、完美转发，你知道的不知道的都在这里
  • 禁止使用 RTTI，尽量在编译期间就确定参数类型，不要搞运行时识别typeid这种代码
  • 使用 C++ 的类型转换, 如 static_cast<>(). 不要使用 int y = (int)x 或 int y = int(x) 等转换方式
  • 明确使用前置还是后置的具体含义，如不考虑返回值，尽量使用效率高的前置++ (++i)
  • 不要使用uint类型，如果需要使用大整型可以考虑int64，否则类型的隐式类型转换会带来很多麻烦 （int32、uint区别）
  • 如无特殊必要不要使用宏，可以考虑使用const或constexpr替代宏，宏的全局作用域很麻烦，如果非要用在马上要使用时才进行 #define, 使用后要立即 #undef
  • google文档说一定不要用宏来控制条件编译(但是我自己还没有查到不用宏如何控制条件编译，或许就不要搞条件编译)
  • 尽可能用 sizeof(varname) 代替 sizeof(type).使用 sizeof(varname) 是因为当代码中变量类型改变时会自动更新. 您或许会用 sizeof(type) 处理不涉及任何变量的代码，比如处理来自外部或内部的数据格式，这时用变量就不合适了
  • 类型名如果过长的话可以考虑使用auto关键字
  • 注释统一使用 // ，不要通过注释禁用代码，擅用git，不要为易懂的代码写注释
  • 写完代码后记得format，VS Code(windows快捷键) shift + alt + F ，每个项目最好都有统一的.clang_format文件
  • 使用C++的string和stream替代C语言风格的char*，使用std::ostream和std::cout替代printf()、sprintf()等
  • 尽量使用STL标准库的容器而不是C语言风格的数组，数组的越界访问之类当时是不会报错的，反而可能弄脏堆栈信息，导致奇奇怪怪难以排查的bug
  • 可以更多的使用模板元编程，尽量多的使用constexpr等编译器计算，编译器是我们的好搭档，个人认为模板元编程以后会是C++的主流技术
  • 可以考虑更多的使用异常处理方式，而不是C语言风格的errno错误码等，这里可以参考团队还在禁用异常处理吗？
  • 一行尽量不要超过120个字符，一个函数尽量不要超过40行，同时一个文件尽量控制在500行内.（不强求）

善用工具

clang-format

  • 安装
    mac： brew install clang-format
  • 使用
    • 生成配置文件 .clang-format
      clang-format -style=LLVM -dump-config> .clang-format
      -style=LLVM|Google|Chromium|Mozilla|Webkit
    • 修改配置文件

VSCode设置

同时每个项目使用统一的.clang_format文件，统一规范代码格式，所有的换行符都要用LF格式，不要用CRLF格式，在右下角可以设置。
在gitee/github上传一份自己的 .clang_format

参考

《C++代码整洁之道》

《Google C++编码规范》

Astyle: http://astyle.sourceforge.net/

clang-format:http://clang.llvm.org/docs/ClangFormat.html

http://universalindent.sourceforge.net/

总结回顾

工具

代码格式化

clang-format

https://clang.llvm.org/docs/ClangFormat.html
https://www.kernel.org/doc/html/latest/process/clang-format.html

安装

https://releases.llvm.org/download.html
Centos8：sudo yum install -y git-clang-format
Mac：sudo brew install clang-format

配置

生成模板文件，再根据自身需要进行修改

生成.clang-format文件，XXX填LLVM, GNU, Google, Chromium, Microsoft, Mozilla, WebKit，PATH填写文件存放路径

  1. clang-format -style=XXX -dump-config > PATH/.clang-format

使用

命令

以Google方式格式化并写入
clang-format -style=google -i main.c

.clang-format文件

在同级目录下存放.clang-format文件，并设置格式化选项-style=file
clang-format -style=file -i main.c

VSCode

插件
Clang-Format：https://marketplace.visualstudio.com/items?itemName=xaver.clang-format
设置
保存文件自动格式化：editor.formatOnSave: true
添加可执行命令clang-format到PATH，否则设置（绝对路径）：
“clang-format.executable”: “/usr/bin/clang-format”

https://clang.llvm.org/docs/ClangFormatStyleOptions.html

  1. ---
  2. # 语言: None, Cpp, Java, JavaScript, ObjC, Proto, TableGen, TextProto
  3. Language:    Cpp
  4. # BasedOnStyle:    LLVM
  5. # 访问说明符(public、private等)的偏移
  6. AccessModifierOffset:    -4
  7. # 开括号(开圆括号、开尖括号、开方括号)后的对齐: Align, DontAlign, AlwaysBreak(总是在开括号后换行)
  8. AlignAfterOpenBracket:    Align
  9. # 连续赋值时，对齐所有等号
  10. AlignConsecutiveAssignments:    true
  11. # 连续声明时，对齐所有声明的变量名
  12. AlignConsecutiveDeclarations:    true
  13. # 左对齐逃脱换行(使用反斜杠换行)的反斜杠
  14. AlignEscapedNewlinesLeft:    true
  15. # 水平对齐二元和三元表达式的操作数
  16. AlignOperands:    true
  17. # 对齐连续的尾随的注释
  18. AlignTrailingComments:    true
  19. # 允许函数声明的所有参数在放在下一行
  20. AllowAllParametersOfDeclarationOnNextLine:    true
  21. # 允许短的块放在同一行
  22. AllowShortBlocksOnASingleLine:    false
  23. # 允许短的case标签放在同一行
  24. AllowShortCaseLabelsOnASingleLine:    false
  25. # 允许短的函数放在同一行: None, InlineOnly(定义在类中), Empty(空函数), Inline(定义在类中，空函数), All
  26. AllowShortFunctionsOnASingleLine:    Empty
  27. # 允许短的if语句保持在同一行
  28. AllowShortIfStatementsOnASingleLine:    false
  29. # 允许短的循环保持在同一行
  30. AllowShortLoopsOnASingleLine:    false
  31. # 总是在定义返回类型后换行(deprecated)
  32. AlwaysBreakAfterDefinitionReturnType:    None
  33. # 总是在返回类型后换行: None, All, TopLevel(顶级函数，不包括在类中的函数), 
  34. #   AllDefinitions(所有的定义，不包括声明), TopLevelDefinitions(所有的顶级函数的定义)
  35. AlwaysBreakAfterReturnType:    None
  36. # 总是在多行string字面量前换行
  37. AlwaysBreakBeforeMultilineStrings:    false
  38. # 总是在template声明后换行
  39. AlwaysBreakTemplateDeclarations:    false
  40. # false表示函数实参要么都在同一行，要么都各自一行
  41. BinPackArguments:    true
  42. # false表示所有形参要么都在同一行，要么都各自一行
  43. BinPackParameters:    true
  44. # 大括号换行，只有当BreakBeforeBraces设置为Custom时才有效
  45. BraceWrapping:   
  46.   # class定义后面
  47.   AfterClass:    false
  48.   # 控制语句后面
  49.   AfterControlStatement:    false
  50.   # enum定义后面
  51.   AfterEnum:    false
  52.   # 函数定义后面
  53.   AfterFunction:    false
  54.   # 命名空间定义后面
  55.   AfterNamespace:    false
  56.   # ObjC定义后面
  57.   AfterObjCDeclaration:    false
  58.   # struct定义后面
  59.   AfterStruct:    false
  60.   # union定义后面
  61.   AfterUnion:    false
  62.   # catch之前
  63.   BeforeCatch:    true
  64.   # else之前
  65.   BeforeElse:    true
  66.   # 缩进大括号
  67.   IndentBraces:    false
  68. # 在二元运算符前换行: None(在操作符后换行), NonAssignment(在非赋值的操作符前换行), All(在操作符前换行)
  69. BreakBeforeBinaryOperators:    NonAssignment
  70. # 在大括号前换行: Attach(始终将大括号附加到周围的上下文), Linux(除函数、命名空间和类定义，与Attach类似), 
  71. #   Mozilla(除枚举、函数、记录定义，与Attach类似), Stroustrup(除函数定义、catch、else，与Attach类似), 
  72. #   Allman(总是在大括号前换行), GNU(总是在大括号前换行，并对于控制语句的大括号增加额外的缩进), WebKit(在函数前换行), Custom
  73. #   注：这里认为语句块也属于函数
  74. BreakBeforeBraces:    Custom
  75. # 在三元运算符前换行
  76. BreakBeforeTernaryOperators:    true
  77. # 在构造函数的初始化列表的逗号前换行
  78. BreakConstructorInitializersBeforeComma:    false
  79. # 每行字符的限制，0表示没有限制
  80. ColumnLimit:    200
  81. # 描述具有特殊意义的注释的正则表达式，它不应该被分割为多行或以其它方式改变
  82. CommentPragmas:    '^ IWYU pragma:'
  83. # 构造函数的初始化列表要么都在同一行，要么都各自一行
  84. ConstructorInitializerAllOnOneLineOrOnePerLine:    false
  85. # 构造函数的初始化列表的缩进宽度
  86. ConstructorInitializerIndentWidth:    4
  87. # 延续的行的缩进宽度
  88. ContinuationIndentWidth:    4
  89. # 去除C++11的列表初始化的大括号{后和}前的空格
  90. Cpp11BracedListStyle:    false
  91. # 继承最常用的指针和引用的对齐方式
  92. DerivePointerAlignment:    false
  93. # 关闭格式化
  94. DisableFormat:    false
  95. # 自动检测函数的调用和定义是否被格式为每行一个参数(Experimental)
  96. ExperimentalAutoDetectBinPacking:    false
  97. # 需要被解读为foreach循环而不是函数调用的宏
  98. ForEachMacros:    [ foreach, Q_FOREACH, BOOST_FOREACH ]
  99. # 对#include进行排序，匹配了某正则表达式的#include拥有对应的优先级，匹配不到的则默认优先级为INT_MAX(优先级越小排序越靠前)，
  100. #   可以定义负数优先级从而保证某些#include永远在最前面
  101. IncludeCategories: 
  102.   - Regex:    '^"(llvm|llvm-c|clang|clang-c)/'
  103.     Priority:    2
  104.   - Regex:    '^(<|"(gtest|isl|json)/)'
  105.     Priority:    3
  106.   - Regex:    '.*'
  107.     Priority:    1
  108. # 缩进case标签
  109. IndentCaseLabels:    false
  110. # 缩进宽度
  111. IndentWidth:    4
  112. # 函数返回类型换行时，缩进函数声明或函数定义的函数名
  113. IndentWrappedFunctionNames:    false
  114. # 保留在块开始处的空行
  115. KeepEmptyLinesAtTheStartOfBlocks:    true
  116. # 开始一个块的宏的正则表达式
  117. MacroBlockBegin:    ''
  118. # 结束一个块的宏的正则表达式
  119. MacroBlockEnd:    ''
  120. # 连续空行的最大数量
  121. MaxEmptyLinesToKeep:    1
  122. # 命名空间的缩进: None, Inner(缩进嵌套的命名空间中的内容), All
  123. NamespaceIndentation:    Inner
  124. # 使用ObjC块时缩进宽度
  125. ObjCBlockIndentWidth:    4
  126. # 在ObjC的@property后添加一个空格
  127. ObjCSpaceAfterProperty:    false
  128. # 在ObjC的protocol列表前添加一个空格
  129. ObjCSpaceBeforeProtocolList:    true
  130. # 在call(后对函数调用换行的penalty
  131. PenaltyBreakBeforeFirstCallParameter:    19
  132. # 在一个注释中引入换行的penalty
  133. PenaltyBreakComment:    300
  134. # 第一次在<<前换行的penalty
  135. PenaltyBreakFirstLessLess:    120
  136. # 在一个字符串字面量中引入换行的penalty
  137. PenaltyBreakString:    1000
  138. # 对于每个在行字符数限制之外的字符的penalty
  139. PenaltyExcessCharacter:    1000000
  140. # 将函数的返回类型放到它自己的行的penalty
  141. PenaltyReturnTypeOnItsOwnLine:    60
  142. # 指针和引用的对齐: Left, Right, Middle
  143. PointerAlignment:    Left
  144. # 允许重新排版注释
  145. ReflowComments:    true
  146. # 允许排序#include
  147. SortIncludes:    true
  148. # 在C风格类型转换后添加空格
  149. SpaceAfterCStyleCast:    false
  150. # 在赋值运算符之前添加空格
  151. SpaceBeforeAssignmentOperators:    true
  152. # 开圆括号之前添加一个空格: Never, ControlStatements, Always
  153. SpaceBeforeParens:    ControlStatements
  154. # 在空的圆括号中添加空格
  155. SpaceInEmptyParentheses:    false
  156. # 在尾随的评论前添加的空格数(只适用于//)
  157. SpacesBeforeTrailingComments:    2
  158. # 在尖括号的<后和>前添加空格
  159. SpacesInAngles:    true
  160. # 在容器(ObjC和JavaScript的数组和字典等)字面量中添加空格
  161. SpacesInContainerLiterals:    true
  162. # 在C风格类型转换的括号中添加空格
  163. SpacesInCStyleCastParentheses:    true
  164. # 在圆括号的(后和)前添加空格
  165. SpacesInParentheses:    true
  166. # 在方括号的[后和]前添加空格，lamda表达式和未指明大小的数组的声明不受影响
  167. SpacesInSquareBrackets:    true
  168. # 标准: Cpp03, Cpp11, Auto
  169. Standard:    Cpp11
  170. # tab宽度
  171. TabWidth:    4
  172. # 使用tab字符: Never, ForIndentation, ForContinuationAndIndentation, Always
  173. UseTab:    Never
  174. ...

注意： 一般不全部重定义规则, 提供了BasedOnStyle标识让我们来重定义部分格式

  1. ---
  2. # We'll use defaults from the LLVM style, but with 4 columns indentation.
  3. BasedOnStyle: LLVM
  4. IndentWidth: 4
  5. ---
  6. Language: Cpp
  7. # Force pointers to the type for C++.
  8. DerivePointerAlignment: false
  9. PointerAlignment: Left
  10. ---
  11. Language: JavaScript
  12. # Use 100 columns for JS.
  13. ColumnLimit: 100
  14. ---
  15. Language: Proto
  16. # Don't format .proto files.
  17. DisableFormat: true
  18. ---
  19. Language: CSharp
  20. # Use 100 columns for C#.
  21. ColumnLimit: 100
  22. ...

静态代码检查

cppcheck

基于正则表达式

clang-tidy

基于语法分析树
vs正则表达式，速度慢但检查更全面、准确、
自行添加一些自定义检查规则

参考文档

TODO

  • 编写脚本，自动检查并修复项目中的代码格式