10分钟掌握MuJoCo编码规范：GoogleDeepMind物理引擎代码标准

MuJoCo（Multi-Joint dynamics with Contact）作为Google DeepMind开发的多关节接触动力学物理引擎，其代码库遵循一套兼顾紧凑性与可读性的内部一致规范。本文档将系统解析STYLEGUIDE.md中的核心要求，帮助开发者快速掌握不同语言模块的编码标准。

代码类型划分与规范适用范围

MuJoCo代码库包含三种主要类型，各自遵循不同标准：

代码类型	所在目录	规范标准	状态
C核心代码	include/、src/	内部C规范	主要维护
遗留C++	src/user/、src/xml/	逐步迁移	待重构
新开发代码	test/、python/、unity/	Google C++风格	积极开发

命名约定

核心C代码遵循文档化的命名约定，公共头文件函数需包含规范文档字符串。例如include/mujoco/mujoco.h中的函数声明必须以大写字母开头并以句号结束。

C代码规范详解

缩进与行宽

采用2空格缩进（禁止使用制表符），行长度限制为100字符。特殊场景如碰撞表可适当放宽，参考src/engine/engine_collision_driver.c中的长行实现。

注释规范

代码注释需满足"仅读注释即可理解函数逻辑"的标准：

• 单行注释前需空行（代码块顶部除外）
• 采用小写字母开头且不加句号（公共头文件的文档字符串除外）
• 函数声明注释需完整描述功能

示例：

// transpose matrix
void mju_transpose(mjtNum* res, const mjtNum* mat, int nr, int nc) {
  for (int i=0; i < nr; i++) {
    for (int j=0; j < nc; j++) {
      res[j*nr+i] = mat[i*nc+j];
    }
  }
}

大括号风格

使用附着式K&R风格，即使单行代码块也需大括号：

if (quat[0] == 1 && quat[1] == 0 && quat[2] == 0 && quat[3] == 0) {
  mju_copy3(res, vec);
}

允许在if/else块中使用分离式大括号以便插入注释：

// null quat: copy vec
if (condition) {
  // implementation
}

// regular processing
else {
  // implementation
}

变量声明

正从C89风格迁移至C99标准：

• 新代码要求变量在最小作用域声明
• for循环迭代变量应在循环内声明
• 编辑现有函数时请协助迁移变量作用域

Python代码规范

Python代码需使用pyink和isort工具格式化：

pip install pyink isort
pyink your_script.py  # 格式化代码
isort your_script.py  # 整理导入

遵循Google Python风格指南，相关配置可参考python/pyproject.toml和python/MANIFEST.in。

一致性原则与贡献建议

当规范未明确规定时，遵循"与现有代码最大程度保持一致"原则。贡献代码前建议：

1. 参考同类型文件的编码风格
2. 运行test/sample/compile_test.sh验证编译
3. 通过CONTRIBUTING.md了解贡献流程

代码审查关注点

• 公共头文件是否包含完整文档字符串
• 变量作用域是否符合C99标准
• 注释是否满足可读性要求
• 格式是否通过自动化工具校验

掌握这些规范将帮助开发者编写符合MuJoCo项目标准的高质量代码，加速PR审核流程。建议定期查阅STYLEGUIDE.md获取最新更新。