NVIDIA Falcor项目C++与Slang编码规范详解

NVIDIA Falcor项目C++与Slang编码规范详解

前言

NVIDIA Falcor作为一款实时渲染框架，其代码质量直接关系到项目的可维护性和扩展性。本文将深入解析Falcor项目中的C++和Slang编码规范，帮助开发者快速掌握项目代码风格要求，编写出符合规范的优质代码。

编码规范的核心原则

1. 一致性优先：规范可能不完全符合个人喜好，但保持代码风格统一至关重要
2. 可读性至上：代码是沟通媒介，应优先考虑可读性和可维护性
3. 最小干扰原则：修改代码时应保持原有风格，避免不必要的"清理"操作

文件组织规范

文件命名与结构

• 命名规则：使用PascalCase命名法，文件名应反映其中定义的主要类/类型
• C++文件：
  • 头文件扩展名.h，源文件.cpp
  • 头文件必须自包含（可独立编译）
  • 使用#pragma once防止重复包含
• Slang文件：
  • 模块文件使用.slang扩展名
  • 包含文件使用.slangh
  • 着色器入口文件添加类型后缀（如.rt.slang表示光线追踪）

包含顺序

源文件包含应分组并按以下顺序排列：

1. 关联头文件
2. 同项目其他本地头文件
3. 其他项目本地头文件
4. 第三方库头文件（使用#include <...>）
5. STL头文件
6. C库头文件（优先使用C++风格如<cmath>）

命名空间与命名规范

命名空间规则

• 使用PascalCase命名法
• Falcor目录下代码应位于Falcor命名空间
• 禁止在头文件中使用using namespace
• 禁止使用using namespace std
• 优先使用匿名命名空间而非static

命名约定详解

| 代码元素 | 命名规则 | |---------|----------| | 类/结构体/枚举 | PascalCase | | 常量 | kCamelCase | | 枚举值 | PascalCase | | 函数 | camelCase | | 公有成员变量 | camelCase | | 私有/保护成员 | mCamelCase | | 静态成员 | sCamelCase | | 全局变量 | gCamelCase | | 局部变量 | camelCase | | 宏 | UPPER_SNAKE_CASE |

命名最佳实践

1. 方法命名：必须使用动词开头，明确表达行为

   vector.normalize();  // 正确
   vector.normal();     // 错误
   

2. 布尔命名：

   • 变量使用状态描述（enabled, visible）
   • 方法使用疑问形式（isEnabled(), hasChildren()）

3. 避免冗余：

   line.getLength();   // 正确
   line.getLineLength(); // 错误
   

4. 计算密集型方法：使用compute前缀

   wave.computeHeight(); // 优于 wave.getHeight()
   

现代C++特性应用

类型系统

1. 使用using而非typedef

   using IndexVector = std::vector<uint32_t>;  // 推荐
   

2. 使用明确大小的类型

   int32_t width;  // 推荐
   int width;      // 不推荐
   

3. 使用enum class替代传统enum

智能指针规范

1. 共享所有权：

   • 使用std::shared_ptr
   • 定义类型别名：

     using SharedPtr = std::shared_ptr<MyClass>;  // 类内
     using MyClassSharedPtr = std::shared_ptr<MyClass>;  // 类外
     

2. 独占所有权：优先使用std::unique_ptr

3. 参数传递：

   • 不保留引用时使用const &或原始指针
   • 需要获取所有权时按值传递SharedPtr

类设计原则

1. 使用override明确重写虚方法
2. 避免使用friend
3. 常量定义：

   static constexpr float kPi = 3.1415926f;  // C++17推荐
   

Slang着色器语言规范

1. 命名与格式：与C++规范保持一致
2. 结构体使用：作为数据和代码容器（无类概念）
3. 浮点数表示：

   float f = 1.5f;  // 正确
   float f = 1.5;   // 可能产生性能问题
   

4. 入口点：同一程序的各着色阶段应定义在同一文件中

代码格式化细则

缩进与空格

1. 基础规则：

   • 使用4个空格（非制表符）
   • 大括号独占一行
   • 条件语句后必须缩进

2. 条件语句：

   if (condition)  // 正确
       doSomething();
   
   if (condition) doSomething();  // 仅适用于极简单语句
   

3. 单行函数：

   int getValue() const { return mValue; }  // 允许
   

间距规范

1. 函数调用：

   setColor(1.0f, 0.5f, 0.0f);  // 正确
   setColor (1.0f,0.5f,0.0f);   // 错误
   

2. 参数对齐：

   Matrix::Matrix(float m11, float m12, float m13, float m14,
                  float m21, float m22, float m23, float m24)  // 参数对齐
   

总结

遵循Falcor编码规范不仅能提高代码质量，还能显著提升团队协作效率。记住，规范的核心目标是保持一致性，而非追求个人偏好。当存在疑问时，应优先参考项目现有代码的风格，确保新代码能够无缝融入现有代码库。

通过掌握这些规范要点，开发者可以更快地为Falcor项目贡献高质量代码，同时也能培养出良好的编程习惯，提升自身的代码素养。