T-UP 代码规范

沈阳航空航天大学TUP机器人俱乐部代码规范

一、规范前言

为统一团队代码风格，提升代码可读性、可维护性与协作效率，减少开发过程中的格式混乱、逻辑隐患及合并冲突，保障项目高效推进，特制定本代码规范。俱乐部所有成员参与校内研发、竞赛项目、代码提交时，需严格遵循本规范，共同维护整洁规范的团队代码生态

---

二、通用基础规范

2.1 编码与格式

1. 所有代码文件统一采用UTF-8编码，换行符使用LF格式（Linux/Unix标准），避免Windows系统CRLF格式导致的代码冲突

2. 缩进统一使用2个空格，严禁使用Tab键缩进，禁止空格与Tab混用，保证跨平台、跨编辑器代码格式完全一致

• 1. 代码不占横向宽度，不易换行
• 2. 方便查看嵌套多层
• 3. 区分手写代码与工具自动生成代码

3. 单行代码长度不超过60字符，超出部分需按逻辑合理换行，换行后层级缩进*2对齐，避免代码横向滚动

4. 运算符两侧、逗号、分号后需添加单个空格；函数参数、数组元素之间的空格保持统一

5. 代码块、函数、类之间保留1个空行，避免代码过于紧凑

2.2 文件命名规则

1. 所有文件、文件夹统一采用小写字母+下划线的snake_case命名风格，禁止使用中文、空格、特殊字符及大写字母(ROS2特殊文件除外)

2. 代码文件后缀遵循语言标准：C++为 .cpp / .hpp 、C为 .c / .h 、Python为 .py 、配置文件为 .yaml

3. ROS2功能包、节点文件、消息/服务/Action文件，命名需贴合功能，简洁直观，与ROS2官方命名规范保持一致

2.3 标识符命名规范

1. 普通变量：采用标准蛇形命名，复合类型变量添加类型前缀/后缀，如 robot_speed，camera_deque

2. 类成员变量：采用标准蛇形命名，添加 _ 后缀，如 chassis_power_ 、 target_position_

3. 常量: 采用尖叫蛇形命名，如 TARGET_VALUE

4. 宏定义：全大写字母加下划线，如 MAX_MOTOR_SPEED 、 NODE_NAME 优先使用 const 常量替代宏定义

5. 类、结构体、枚举类型：采用大驼峰，如 LidarData

6. 命名空间：采用标准蛇形命名，如 rm_chassis ，禁止嵌套超过3层

7. 函数、方法：采用小驼峰, 如 findArmor

2.4 语风规范

1. 花括号遵循K&R风格：左花括号不换行，右花括号单独成行

2. 条件判断、循环、函数体即使只有单行代码，也必须添加花括号

3. 指针、引用符号紧贴数据类型，而非变量名

4. 头文件统一使用传统的 #ifndef/#define/#endif 写法防止重复包含

5. 按需引入命名空间，禁止使用 using namespace std; ，避免命名空间污染

6. 优先使用C++11及以上标准，采用智能指针（ std::unique_ptr / std::shared_ptr ）替代裸指针，减少内存泄漏风险

7. 布尔值，变量，指针判断，必须左面显式写出判断值，右面是布尔值，变量，指针，避免判断误错写成赋值，方便判断类型

8. 禁止使用无意义单字符变量（循环临时变量i、j、k除外），所有命名需见名知意，杜绝拼音、缩写滥用

9. 跨模块、跨节点代码避免强耦合，优先封装函数、类实现功能复用，提升代码可移植性

10. 函数功能单一化，单个函数代码行数不超过80行，复杂逻辑拆分为子函数，提升可读性

11. 避免使用全局变量，如需全局使用，添加 static 限制作用域，并添加详细注释说明用途

12. 关键控制逻辑、硬件驱动、ROS2通信交互代码，需添加异常处理逻辑

13. 文件头注释：所有代码文件开头必须添加文件注释，标注文件功能、作者、创建时间、修改记录，模板如下：

14. 代码注释

• 1. 函数必须在头文件添加文档注释，说明功能、参数、返回值、异常场景
• 2. 关键逻辑、复杂算法：必须添加行内注释，解释代码用途而非语法
• 3. 禁止无意义注释：代码修改后同步更新对应注释，避免代码与注释脱节

---

三、项目工程结构规范

3.1 普通项目结构

1. 一级目录规则

• .vscode/ ：编辑器配置目录
• 3rdparty/ ：第三方依赖库目录
• assets/ ：静态资源目录
• build/ ：编译产物目录，且必须加入 .gitignore
• config/ ：运行配置目录
• logs/ ：日志输出目录，且建议加入 .gitignore
• src/ ：核心源码目录
• tests/ ：测试代码目录
• .gitignore ：Git忽略文件
• CMakeLists.txt ：项目构建文件 ...

2. src目录：代码按模块拆分  driver/ （驱动）  algorithm/ （算法）  utils/ （工具函数） ...

3.2 ROS2工作空间结构

1. 严格遵循ROS2官方工程结构

---

四、Git规则

4.1 分支管理

1. main/master 分支：仅存放稳定、可直接运行的正式代码，禁止直接修改、提交

2. dev 分支：团队统一开发分支，所有功能开发完成后合并至此

3. 功能分支：以 feature/功能名 命名，如 feature/chassis_optimize ，开发完成后提交PR合并至dev分支

4.2 提交信息规范

1. 提交信息格式：[类型] 具体描述 ，类型分为以下6种，描述简洁明确：

•  feat ：新增功能、模块、节点
•  fix ：修复bug、通信异常、逻辑错误
•  docs ：修改注释、规范、说明文档
•  style ：代码格式调整（不影响逻辑）
•  refactor ：代码重构、优化逻辑
•  test ：添加测试代码、调试逻辑

2. 禁止编写冗余、废弃、注释掉的垃圾代码，提交前清理无效代码，保证代码整洁

3. 严禁提交 build/ log/ install/ 目录!!!!! 可配置.gitignore(Git忽略文件)避免

4.3 项目测试与审核规范

1. 所有代码提交前，需完成本地编译、运行测试，确保无报错、无异常闪退
2. 提交代码，需经过全流程联调，杜绝无效代码、冗余逻辑、格式混乱问题
3. 团队代码合并前，由组负责人进行规范审核，不符合本规范的代码需修改后再提交

---

五、附则

1. 本规范适用于沈航TUP机器人俱乐部所有校内研发、学科竞赛、对外合作项目
2. 本规范可根据技术迭代、项目需求进行补充修订，最终解释权归俱乐部技术组所有
3. 所有俱乐部成员需自觉遵守本规范，共同维护团队代码质量，提升协作开发效率

2026-04-30 YinKang'an