Mbed OS 文档翻译之参考（贡献（指南（风格）））

最新推荐文章于 2018-11-06 13:55:14 发布

XinLiBK

最新推荐文章于 2018-11-06 13:55:14 发布

阅读量359

点赞数 1

分类专栏： Mbed OS 文章标签： Mbed Mbed OS Mbed OS 5

Mbed OS 专栏收录该内容

146 篇文章 30 订阅

订阅专栏

风格

Arm Mbed OS 代码库托管在 GitHub 上，您可以提交新功能或错误修复。请遵循提交中的 GitHub 拉取请求指南和编码样式指南。

提示: 请阅读 CLA 和工作流程部分，以了解流程和法律要求。

代码接受

在 CLA 到位并且代码经过自动化测试之后，开发人员将对拉取请求进行查看和评论。如果一切都很好并且可以接受，那么您的代码将准备好合并到中央开发分支。

编码风格

无论您是在编写新代码还是修复现有代码中的错误，请遵循 Mbed OS 编码风格。

Mbed OS 遵循 K&R 风格，至少有两个例外（可以在代码示例下面的列表中找到）。

这种编码风格的唯一例外是第三方代码。应将第三方代码添加到位于 Mbed OS 根目录中的 .astyleignore 文件中。

您可以使用 Artistic Style (AStyle) 来格式化代码。使用命令行开关选择正确的样式并指向要编辑的文件：

astyle -n --options=.astylerc $(full_path_to_file)

文件 .astylerc 定义了 Mbed OS 代码样式，它位于 Mbed OS 根目录中。

代码示例

static const PinMap PinMap_ADC[] = {
    {PTC2, ADC0_SE4b, 0},
    {NC , NC , 0}
};

uint32_t adc_function(analogin_t *obj, uint32_t options)
{
    uint32_t instance = obj->adc >> ADC_INSTANCE_SHIFT;
    switch (options) {
        case 1:
            timeout = 6;
            break;
        default:
            timeout = 10;
            break;
    }

    while (!adc_hal_is_conversion_completed(instance, 0)) {
        if (timeout == 0) {
            break;
        } else {
            timeout--;
        }
    }

    if (obj->adc == ADC_CHANNEL0) {
        adc_measure_channel(instance);
        adc_stop_channel(instance);
    } else {
        error("channel not available");
    }

#if DEBUG
    for (uint32_t i = 0; i < 10; i++) {
        printf("Loop : %d", i);
    }
#endif
    return adc_hal_get_conversion_value(instance, 0);
}

规则

缩进 - 四个空格。请不要使用 Tab。
大括号 - K＆R 风格。
一种真正的大括号样式（1TBS） - 对 if，else，while 和 for 类型的语句使用大括号（来自 K＆R 的异常）。
每个声明一行。
预处理器宏从新行的开头开始；里面的代码根据它上面的代码缩进。
switch 内的情况是缩进的（K＆R 除外）。
类型为 if，while，for，switch 的语句之后的空格。这同样适用于二元运算符（如 +，*）和三元运算符（？和：)。
每行最好最多 120 个字符。
注释应使用正确的拼写和语法。
对于指针或引用，符号 * 或＆与名称相邻（analogin_t *obj，analogin_t ＆obj）。如果省略名称，请在类型和 * 之间放置空格（例如 int * 或 int ＆）。
对于函数返回指针或引用，符号 * 或＆与函数名称（int *func() 或 int ＆func()）相邻。
不要在行尾留下尾随空格。
空行应该没有尾随空格。
Unix 行结尾是文件的默认选项。
使用大写字母表示宏。
文件末尾应该有一个空行。

命名约定

类

以大写字母开头，其中的每个单词也以大写字母（AnalogIn，BusInOut）开头。
方法包含小写字母，单词用下划线分隔。
私有成员以下划线开头：__User 定义的类型（typedef）））。
结构体 - 后缀 _t - 表示它是用户定义的类型。
枚举 - 类型名称和值名称 - 与类相同的命名约定（例如 MyNewEnum）。

功能

包含小写字母（作为类中的方法）。
由下划线分隔的单词（wait_ms，read_u16）。

举个例子：

#define ADC_INSTANCE_SHIFT 8 

class AnalogIn {
public:
    /** Create an AnalogIn connected to the specified pin.
     *
     * @param pin AnalogIn pin to connect to
     * @param name (optional) A string to identify the object
     */
    AnalogIn(PinName pin)
    {
        analogin_init(&_adc, pin);
    }

    /** Read the input voltage, represented as a float in the range [0.0, 1.0].
     *
     * @returns
     * 	A floating-point value representing the current input voltage, measured as a percentage
     */
    uint32_t read()
    {
        return analogin_read(&_adc, operation);
    }
protected:
    analogin_t _adc;
};

typedef enum {
    ADC0_SE0 = (0 << ADC_INSTANCE_SHIFT) | 0,
} ADCName;

struct analogin_s {
    ADCName adc;
};

typedef struct analogin_s analogin_t;

Doxygen 文档

所有功能和方法都应包含使用 Doxygen 的文档。