NervanaSystems/ngraph 项目代码贡献规范与技术指南

NervanaSystems/ngraph 项目代码贡献规范与技术指南

项目概述

NervanaSystems/ngraph 是一个深度学习编译器项目，其核心设计理念是将计算图视为由基本构建块(ops)组成的计算规范，而非直接执行优化内核的脚本。该项目强调通过编译过程将ops组匹配到后端的最优内核实现。

代码许可要求

所有贡献的代码必须符合Apache 2.0许可证的要求。项目建议贡献者直接采用Apache 2.0许可证提交代码。如果使用其他许可证，需要经过项目维护方的审核才能被接受。

核心设计哲学

ngraph采用独特的设计理念：

1. 计算图作为规范：计算图不是直接执行的脚本，而是由基本构建块(ops)组成的计算规范
2. 编译优化：编译过程负责将ops组匹配到后端的最优内核实现
3. 核心ops扩展：核心ops的添加应该是谨慎的，大多数功能应该通过现有核心ops构建子图来实现

代码风格规范

命名约定

1. 类/类型命名：使用CamelCase风格
2. 模板参数：使用UPPER_SNAKE_CASE风格
3. 变量/函数命名：使用lower_snake_case风格

访问器方法命名

1. get_前缀方法：

   • 应该是外部幂等的
   • 可以执行简单初始化并缓存结果
   • 简单实现可以放在头文件中

2. is_前缀方法：

   • 用于布尔型访问器
   • 替代get_前缀

3. set_前缀方法：

   • 改变对应get_方法的返回值
   • 简单实现可以放在头文件中

变量命名

1. 成员变量：前缀m_
2. 静态成员变量：前缀s_(应尽量少用)

类型别名

避免在头文件顶层使用using定义类型别名。如果确实需要抽象，应该创建一个类。

命名空间使用规范

1. 公共API应放在ngraph命名空间中
2. 实现类使用嵌套命名空间
3. 文件局部名称使用未命名命名空间或static
4. 头文件中禁止顶层using
5. 仅在.cpp文件中使用using std或using ngraph

文件组织规范

1. 文件名：

   • 头文件使用.hpp扩展名
   • 实现文件使用.cpp扩展名
   • 避免在不同目录使用相同文件名

2. 目录结构：

   • 反映命名空间的嵌套层次
   • 单元测试放在tests目录

3. 单元测试文件：

   • 依赖transformer的测试使用TEST(file_name, test_name)形式
   • 独立于transformer的测试：
     • 文件名格式为file_name.in.cpp
     • 包含#include "test_control.hpp"
     • 添加static std::string s_manifest = "${MANIFEST}";
     • 使用NGRAPH_TEST(${BACKEND_NAME}, test_name)格式

代码格式化规范

项目使用clang-format自动格式化代码，主要规则包括：

1. 头文件包含：

   • 分组组织，组间空行分隔
   • 从系统级到第三方再到ngraph的逻辑顺序
   • 使用#include <file>格式表示不经常变化的文件
   • 使用#include "file"格式表示开发中经常变化的文件

2. 防止多重包含：

   • 使用#pragma once指令

3. 初始化语法：

   • 优先使用Foo x{4, 5};而非Foo x(4, 5);

4. 缩进与括号：

   • 即使单行语句也应使用大括号

异常处理规范

1. 使用异常报告问题
2. 禁止使用abort、exit或terminate
3. 错误信息：
   • 避免使用感叹号
   • 尽可能具体明确
   • 考虑最终用户可能通过框架间接看到错误信息

auto关键字使用建议

1. 了解auto的类型推导规则(auto会剥离引用)
2. 避免不必要的auto使用：
   • 不推荐：auto s = Shape{2,3};
   • 推荐：Shape s{2, 3};
3. 在变量名中表明类型信息

变量声明规范

1. 每行只声明一个变量
2. 避免C风格的多变量声明：
   • 不推荐：int x, y, *z;
   • 推荐：

     int x;
     int y;
     int* z;
     

最佳实践建议

1. 局部性原则：代码修改的影响范围应尽量局部化
2. 可读性优先：代码应易于理解其功能
3. 一致性：遵循项目现有风格和约定
4. 谨慎扩展：核心ops的添加应慎重考虑

通过遵循这些规范，开发者可以确保代码质量，保持项目的一致性和可维护性，同时也能更高效地与其他贡献者协作。