C++核心指导原则: 命名和布局建议

C++ Core Guidelines 整理目录

1. 哲学部分
2. 接口(Interface)部分
3. 函数部分
4. 类和类层次结构部分
5. 枚举部分
6. 资源管理部分
7. 表达式和语句部分
8. 性能部分
9. 并发和并行
10. 错误处理
11. 常量和不可变性
12. 泛型编程
13. 源文件
14. 命名和布局建议
15. 标准库
16. 其他规则

命名和布局建议

一致的命名方式和代码布局是非常有益的, 无他, 就是避免在代码风格方面引战(像 Go 语言就内置 fmt 命令来保持代码格式化的一致性).

现实中存在非常多的 C++风格, 不可能将他们统一. 所以这里给出的仅仅是些建议, 并非规则.

但是对于个人开发者或者团队来说, 保存统一风格, 将会降低成员的认知负荷, 减小代码维护的难度. 另外从代码观感上来说也会更舒服. 如果从一个文件跳转到另外一个文件时, 发现代码布局不一样, 那对于阅读者来说会产生一些不必要的麻烦. 显得非常不专业.

NL.1: Don’t say in comments what can be clearly stated in code

• 翻译: 避免在注释中重复代码已经清晰表达的内容.
• 原因: 注释应专注于说明意图和上下文, 而非简单复述代码本身, 以减少冗余并提高可读性.

NL.2: State intent in comments

• 翻译: 在注释中说明意图.
• 原因: 解释为什么这样做有助于其他开发者理解背后的逻辑, 便于维护和改进.

NL.3: Keep comments crisp

• 翻译: 保持注释简洁.
• 原因: 避免在注释中重复代码已经清晰表达的内容, 减少冗余并提高可读性.

NL.4: Maintain a consistent indentation style

• 翻译: 保持一致的缩进风格.
• 原因: 统一的缩进让代码结构更加清晰, 容易追踪代码块, 减少错误.

NL.5: Avoid encoding type information in names

• 翻译: 名字中避免编码类型信息.
• 原因: 首先名字的第一要务是要表达意图, 这对于后续改进更容易. 其次现代 IDE 能够提供类型信息, 名字中包含类型会导致名称过长且不易于维护, 如果该换了类型又得改名字.

NL.7: Make the length of a name roughly proportional to the length of its scope

• 翻译: 名称长度应与其作用域大小成比例.
• 原因: 较小的作用域允许使用简短的名字, 而较大的作用域需要更具描述性的名字来明确含义.

NL.8: Use a consistent naming style

• 翻译: 使用一致的命名风格.
• 原因: 一致性降低了阅读代码时的认知负担, 提高了团队协作效率.

NL.9: Use ALL_CAPS for macro names only

• 翻译: 只对宏名使用全大写.
• 原因: 全大写的命名约定帮助快速识别宏定义, 避免误用.

NL.10: Prefer underscore_style names

• 翻译: 推荐使用下划线风格的命名风格.
• 原因: 下划线连接单词的方式使得名称易于阅读, 特别是在较长的标识符中.

NL.11: Make literals readable

• 翻译: 保证字面值易于阅读.

• 原因: 易于阅读的字面值可以迅速理解, 减少了误解和潜在的编程错误. 现在 C++针对字面值已经做了不少提升, 比如:

  • 数值: int a = 10'000'000; 可以清晰地表示数值.
  • 字符串: auto s = R"({"type": "json", "need_quote": false})"; 可以清晰地表示字符串, 不需要加入很多转义字符.
  • 时间: auto interval = 1h; 可以清晰地表示时间间隔.

  更多关于字面量的总结, 请参考我的博客: Modern C++ 字面量一网打尽

NL.15: Use spaces sparingly

• 翻译: 谨慎使用空格.
• 原因: 合理使用空格可以显著改善代码的可读性和美观度, 但过度使用可能导致混乱.

NL.16: Use a conventional class member declaration order

• 翻译: 采用传统的类成员声明顺序.
• 原因: 传统顺序如 public, protected, private 使代码结构更加清晰, 方便查找特定成员.

NL.17: Use K&R-derived layout

• 翻译: 使用源自 K&R 的布局方式.
• 原因: K&R 风格简洁明了, 是许多开发者的默认选择, 促进了代码的一致性.

NL.18: Use C++-style declarator layout

• 翻译: 使用 C++风格的声明符布局.
• 原因: 符合语言规范的布局方式增强了代码的统一性和可维护性.

NL.19: Avoid names that are easily misread

• 翻译: 避免容易被误读的名字.
• 原因: 易混淆的名字增加了理解难度, 可能导致调试困难和错误.

NL.20: Don’t place two statements on the same line

• 翻译: 不要在同一行放置两个语句.
• 原因: 每个语句单独一行有助于快速定位和修改代码, 简化调试过程.

NL.21: Declare one name (only) per declaration

• 翻译: 每个声明只声明一个名字.
• 原因: 单独声明每个名字提高了代码的清晰度, 减少了可能的解析错误.

NL.25: Don’t use void as an argument type

• 翻译: 不要将 void 作为参数类型.

• 原因: 这个是多余的, 并且只有在需要对 C 保持兼容的时候才有用.

• 示例:

  void f(void);   // bad
  
  void g();       // better
  

NL.26: Use conventional const notation

• 翻译: 使用常规的 const 符号约定.

• 原因: 常规的 const 符号约定对开发者来说更易于理解, 并且可以减少错误.

• 示例:

  const int x = 7;    // OK
  int const y = 9;    // bad
  
  const int *const p = nullptr;   // OK, constant pointer to constant int
  int const *const p = nullptr;   // bad, constant pointer to constant int
  

NL.27: Use a .cpp suffix for code files and .h for interface files

• 翻译: 代码文件使用.cpp 后缀, 接口文件使用.h 后缀.
• 原因: 这个是长久以来的约定. 除非你的项目已经有别的约定, 否则请遵循这个约定.