NanoGUI项目代码贡献与开发规范指南-CSDN博客

本文链接：https://blog.csdn.net/gitblog_00713/article/details/148970612

NanoGUI项目代码贡献与开发规范指南

前言

NanoGUI是一个轻量级的C++ GUI库，专注于为图形应用程序提供简洁高效的界面组件。本文将为开发者详细介绍如何为NanoGUI项目贡献代码，包括bug报告规范、代码提交流程、编码风格要求等重要内容。

问题报告规范

在提交问题报告前，请务必：

确认问题是否已在项目文档中讨论过
准备一个最小可复现示例(MRE)，包含：
- 不依赖外部库的独立代码
- 隔离导致问题的核心函数
- 完整的C++或Python代码片段(根据使用方式选择)

对于功能请求，项目维护者通常只接受附带实现代码的请求。

代码提交流程

提交代码时请遵循以下最佳实践：

分支管理：每个新功能应在独立分支上开发
提交规模：保持PR小而精，便于审查但又有独立价值
测试要求：新增功能必须经过充分测试(如新增Widget)
代码精简：项目追求用最少的代码提供通用解决方案

对于文档更新，请在提交信息前添加[docs]前缀。

多语言支持要求

NanoGUI同时支持C++和Python绑定，因此：

新增API时，必须同时实现C++和Python版本
Python绑定代码应放在python/python.cpp文件中

代码风格规范

基础格式

缩进：使用4个空格，禁止使用制表符
行宽：建议控制在80字符内
指针/引用：修饰符靠近变量名
- 正确：void *p、Color &c
- 错误：void* p、Color& c

模板语法

template <typename T> 
void method() {
    // 实现代码
}

大括号风格

// 正确风格
for (auto &&c : myVec) {
    // 循环体
}

// 错误风格
for(auto &&c : myVec)
{
    // 循环体
}

文档编写规范

项目使用Doxygen生成文档，采用JavaDoc风格注释。

基本结构

/*
 nanogui/file.h -- 文件功能描述

 NanoGUI由Wenzel Jakob开发...
*/
/** \file */

类/结构体文档：

/**
 * \class ClassName header.h nanogui/header.h
 * 
 * 类的详细说明
 */
class ClassName { ... };

注释示例

简单方法：

/// 获取窗口标题
const std::string &caption() const { return mCaption; }

复杂方法：

/**
 * \brief 计算类型大小的无用函数
 *
 * 这里是详细说明...
 *
 * \tparam T 要计算大小的类型
 * \param returnFake 
 *     若为true则返回随机正数
 *     这个注释可以跨多行
 * \return sizeof(T)的结果
 */
template <typename T>
size_t exampleFunction(bool returnFake = false) { ... }

文档样式技巧

Doxygen特性

使用\throws标注异常
使用\remark添加备注
使用\ref创建内部链接

Sphinx/reST集成

在Doxygen注释中使用\rst和\endrst可嵌入reStructuredText：

/**
 * \brief 示例方法
 * \rst
 * .. note::
 *    这里是注意事项
 *
 * .. code-block:: py
 *    print("Python示例")
 * \endrst
 */

待完善文档列表

以下是需要补充文档的模块概览：

| 模块文件 | 需要完善的内容 | |----------------|-----------------------------| | button.h | 大部分成员方法和变量 | | checkbox.h | 全部成员方法和变量 | | colorpicker.h | 构造函数、回调和成员变量 | | ... | ... |