PX4 Guide (main)

中文 (Chinese)

English

中文 (Chinese)

English

Appearance

源代码管理 ​

分支模型 ​

PX4项目采用三分支Git模型：

我们尝试通过变基操作来保留线性提交历史记录（[参考](https://www.atlassian.com/git/tutorials/rewriting - history)），并避免使用 [Github流程](https://docs.github.com/en/get - started/quickstart/github - flow)。然而，由于项目团队分布在全球且开发速度较快，我们有时可能会进行合并操作。

若要贡献新功能，需先 [注册Github账号](https://docs.github.com/en/get - started/signing - up - for - github/signing - up - for - a - new - github - account)，然后 [派生](https://docs.github.com/en/get - started/quickstart/fork - a - repo) 仓库，[创建新分支](https://docs.github.com/en/pull - requests/collaborating - with - pull - requests/proposing - changes - to - your - work - with - pull - requests/creating - and - deleting - branches - within - your - repository)，将 [修改作为提交内容添加](#commits - and - commit - messages)，最后 [发送拉取请求](#pull - requests)。修改内容在通过我们的 持续集成 测试后将会被合并。

所有代码贡献必须遵循宽松的 [BSD 3条款许可证](https://opensource.org/licenses/BSD - 3 - Clause)，并且所有代码不得对使用施加任何进一步限制。

代码风格 ​

PX4使用 Google C++ 风格指南，并做了以下（少量）修改：

INFO

并非所有PX4源代码都符合该风格指南，但你编写的任何 新代码 都应遵循，无论是新文件还是现有文件。如果你更新现有文件，无需使整个文件都符合风格指南，只需确保你修改的代码部分符合即可。

制表符 ​

  • 使用制表符进行缩进（相当于8个空格）。
  • 使用空格进行对齐。

行长 ​

  • 最大行长为120个字符。

文件扩展名 ​

  • 源文件使用 *.cpp 扩展名，而不是 *.cc。

函数和方法名称 ​

  • 函数和方法使用 lowerCamelCase() 风格，以便从视觉上与 ClassConstructors() 和 ClassNames 区分开来。

私有类成员变量名称 ​

  • 私有类成员变量名称使用 _underscore_prefixed_snake_case 风格，而不是 underscore_postfixed_。

类访问控制关键字 ​

  • 在 public:、private: 或 protected: 关键字前 不使用 空格。

代码示例 ​

cpp
class MyClass {
public:

        /**
         * @brief 该函数功能描述。
         *
         * @param[in] input_param 输入参数的清晰描述 [单位]
         * @return 返回值描述 [单位]
         */
        float doSomething(const float input_param) const {
                const float in_scope_variable = input_param + kConstantFloat;
                return in_scope_variable * _private_member_variable;
        }

        void setPrivateMember(const float private_member_variable) { _private_member_variable = private_member_variable; }

        /**
         * @return 返回值描述 [单位]
         */
        float getPrivateMember() const { return _private_member_variable; }

private:

        // 如果常量名称不能完全表明其含义，则需清晰描述常量 [单位]
        static constexpr float kConstantFloat =...;

        // 如果变量名称不能完全表明其含义，则需清晰描述变量 [单位]
        float _private_member_variable{...};
};

提交与提交信息 ​

我们鼓励PX4开发者创建适当的源代码内文档。

INFO

目前源代码文档标准并未强制执行，且代码文档化程度参差不齐。我们希望能有所改进！

目前我们有两种基于源代码的文档类型：

  • PRINT_MODULE_* 方法既用于模块运行时使用说明，也用于本指南中的 模块与命令参考。

  • 我们鼓励在其他 有价值且不冗余 的地方添加源代码内文档。

    TIP

    开发者在命名C++ 实体（类、函数、变量等）时，应使其目的易于推断，从而减少对显式文档的需求。

    • 不要添加可从C++ 实体名称轻易推断出的文档。
    • 在定义变量、常量以及输入/返回参数时，务必指明其单位。
    • 通常，你可能需要添加有关边界情况和错误处理的信息。
    • 如果需要文档说明，应使用 Doxgyen 标签：@class、@file、@param、@return、@brief、@var、@see、@note。[src/modules/events/send_event.h](https://github.com/PX4/PX4 - Autopilot/blob/main/src/modules/events/send_event.h) 就是一个很好的使用示例。

请避免使用“魔法数字”。例如，条件语句中的这个数字从何而来？偏航操纵杆输入的乘数又是怎么回事？

cpp
if (fabsf(yaw_stick_normalized_input) < 0.1f) {
        yaw_rate_setpoint = 0.0f;
}
else {
        yaw_rate_setpoint = 0.52f * yaw_stick_normalized_input;
}

相反，应在头文件中定义具有适当上下文的命名常量：

cpp
// 归一化偏航操纵杆输入的死区阈值
static constexpr float kYawStickDeadzone = 0.1f;

// [弧度/秒] 归一化偏航操纵杆输入的死区阈值
static constexpr float kMaxYawRate = math::radians(30.0f);

并更新源实现代码：

cpp
if (fabsf(yaw_stick_normalized_input) < kYawStickDeadzone) {
        yaw_rate_setpoint = 0.0f;
}
else {
        yaw_rate_setpoint = kMaxYawRate * yaw_stick_normalized_input;
}

提交与提交信息 ​

对于所有非平凡更改，请使用描述性的、多段落的提交信息。精心组织这些信息，使其在单行摘要中有意义，同时又能提供完整细节。

plain
组件：用一句话解释更改内容。Fixes #1234

在摘要行开头加上软件组件名称，可以是模块名称或对其的描述。
（例如，“mc_att_ctrl” 或 “多旋翼姿态控制器”）。

如果在结尾附加问题编号 <Fixes #1234>，当提交合并到主分支时，Github将自动关闭该问题。

信息主体可以包含多个段落。详细描述你所做的更改。链接与此修复相关的问题和飞行日志，或此提交的测试结果。

描述更改及其原因，避免复述代码更改（好的示例：“为GPS接收质量低的飞行器添加额外的安全检查”。不好的示例：“添加 gps_reception_check() 函数”）。

报告人：姓名 <email@px4.io>

对所有提交使用 git commit -s 进行签名。这将在最后一行添加 signed - off - by: 以及你的姓名和电子邮件。

本提交指南基于Linux内核及其他由Linus Torvalds维护的 [项目](https://github.com/torvalds/subsurface - for - dirk/blob/a48494d2fbed58c751e9b7e8fbff88582f9b2d02/README#L88 - L115) 的最佳实践。

拉取请求 ​

Github [拉取请求（PRs）](https://docs.github.com/en/pull - requests/collaborating - with - pull - requests/proposing - changes - to - your - work - with - pull - requests/about - pull - requests) 是向PX4提交新功能和错误修复的主要机制。

它们包含你分支中（相对于主分支）的一组新 [提交内容](#commits - and - commit - messages) 以及更改说明。

更改说明应包括：

  • 对更改内容的概述，要足以让人理解代码的大致目的。
  • 相关问题或支持信息的链接。
  • 关于对PR功能所做测试的信息，并附上飞行日志链接。
  • 如有可能，提供更改前后一般 试飞 的结果。