RT-Thread的编码规范-rt – thread

2023-04-12 12:15:24

一个优秀的项目，必定有优秀的“基因”，而编码规范就是其中之一。

之前给大家分享过很多关于编码规范的内容，今年分享一下RT-Thread的编码规范。

RT-Thread 编程风格

这是一份 RT-Thread 开发人员的开发指引。RT-Thread 做为一份开源软件，它需要由不同的人采用合作的方式完成，这份文档是开发人员的一个指引。RT-Thread 的开发人员请遵守这样的编程风格。同时对于使用 RT-Thread 的用户，也可通过这份文档了解 RT-Thread代码内部一些约定从而比较容易的把握到 RT-Thread 的实现方式。

1.目录名称

目录名称如果无特殊的需求，请使用全小写的形式；目录名称应能够反映部分的意思，例如各芯片移植由其芯片名称构成或芯片类别构成；components 目录下能够反映组件的意义。

2.文件名称

文件名称如果无特殊的需求(如果是引用其他地方，可以保留相应的名称)，请使用全小写的形式。另外为了避免文件名重名的问题，一些地方请尽量不要使用通用化、使用频率高的名称。

设备驱动源码文件：复制drv_class.c的命名方式，如：

drv_spi.c

drv_gpio.c

3.头文件定义

C 语言头文件为了避免多次重复包含，需要定义一个符号。这个符号的定义形式请采用如下的风格：

复制1#ifndef__FILE_H__ 2#define__FILE_H__ 3/*headerfilecontent*/ 4#endif

即定义的符号两侧采用 “__” 以避免重名，另外也可以根据文件名中是否包含多个词语而采用 “_” 连接起来。

4.文件头注释

在每个源文件文件头上，应该包括相应的版权信息，Change Log 记录：

复制 1/* 2*Copyright(c)2006-2020,RT-ThreadDevelopmentTeam 3* 4*SPDX-License-Identifier:Apache-2.0 5* 6*ChangeLogs: 7*DateAuthorNotes 8*2006-03-18Bernardthefirstversion 9*2006-04-26BernardaddsemaphoreAPIs 10*/

例如采用如上的形式。

5.结构体定义

结构体名称请使用小写英文名的形式，单词与单词之间采用 “_” 连接，例如：

复制1structrt_list_node 2{ 3structrt_list_node*next; 4structrt_list_node*prev; 5};

其中，“{“，”}” 独立占用一行，后面的成员定义使用缩进的方式定义。

结构体等的类型定义请以结构体名称加上 “_t” 的形式作为名称，例如：

复制1typedefstructrt_list_nodert_list_t;

因为内核中对象引用方便的缘故，采用了对象内核指针作为类型定义的形式，例如：

复制1typedefstructrt_timer*rt_timer_t;

6.宏定义

在RT-Thread中，请使用大写英文名称作为宏定义，单词之间使用 “_” 连接，例如：

复制1#defineRT_TRUE1

7.函数名称、声明

函数名称请使用小写英文的形式，单词之间使用 “_” 连接。提供给上层应用使用的 API接口，必须在相应的头文件中声明；如果函数入口参数是空，必须使用 void 作为入口参数，例如：

复制1rt_thread_trt_thread_self(void);

内部静态函数命名：以下划线开头，使用复制_class_method格式，不携带复制_rt_开头，如内核或驱动文件中的函数命名：

复制1/*IPCobjectinit*/ 2staticrt_err_t_ipc_object_init() 3 4/*UARTdriverops*/ 5staticrt_err_t_uart_configure() 6staticrt_err_t_uart_control()

调用注册设备接口的函数命名：使用复制rt_hw_class_init()格式，举例：

复制1intrt_hw_uart_init(void) 2intrt_hw_spi_init(void)

8.注释编写

请使用英文做为注释，使用中文注释将意味着在编写代码时需要来回不停的切换中英文输入法从而打断编写代码的思路。并且使用英文注释也能够比较好的与中国以外的技术者进行交流。

语句注释：

源代码的注释不应该过多，更多的说明应该是代码做了什么，仅当个别关键点才需要一些相应提示性的注释以解释一段复杂的算法它是如何工作的。对语句的注释只能写在它的上方或右方，其他位置都是非法的。

复制1/*你的英文注释*/

函数注释：

注释以复制/**开头，以复制*/结尾，中间写入函数注释，组成元素如下，每个元素描述之间空一行，且首列对齐：

@brief + 简述函数作用。在描述中，着重说明该函数的作用，每句话首字母大写，句尾加英文句号。

@note + 函数说明。在上述简述中未能体现到的函数功能或作用的一些点，可以做解释说明，每句话首字母大写，句尾加英文句号。

@see + 相关 API 罗列。若有与当前函数相关度较高的 API，可以进行列举。

@param + 以参数为主语 + be 动词 + 描述，说明参数的意义或来源。

@return + 枚举返回值 + 返回值的意思，若返回值为数据，则直接介绍数据的功能。

@warning + 函数使用注意要点。在函数使用时，描述需要注意的事项，如使用环境、使用方式等。每句话首字母大写，句尾加英文句号。

注释模版请参见：rt-thread/src/ipc.c 源码文件，英文注释请参考使用 grammarly 以及谷歌翻译。

复制 1/** 2*@briefThefunctionwillinitializeastaticeventobject. 3* 4*@noteForthestaticeventobject,itsmemoryspaceisallocatedbythecompilerduringcompiling, 5*andshallplacedontheread-writedatasegmentorontheuninitializeddatasegment. 6*Bycontrast,thert_event_create()functionwillallocatememoryspaceautomatically 7*andinitializetheevent. 8* 9*@seert_event_create() 10* 11*@parameventisapointertotheeventtoinitialize.Itisassumedthatstoragefortheevent 12*willbeallocatedinyourapplication. 13* 14*@paramnameisapointertothenamethatgiventotheevent. 15* 16*@paramvalueistheinitialvaluefortheevent. 17*Ifwanttoshareresources,youshouldinitializethevalueasthenumberofavailableresources. 18*Ifwanttosignaltheoccurrenceofanevent,youshouldinitializethevalueas0. 19* 20*@paramflagistheeventflag,whichdeterminesthequeuingwayofhowmultiplethreadswait 21*whentheeventisnotavailable. 22*TheeventflagcanbeONEofthefollowingvalues: 23* 24*RT_IPC_FLAG_PRIOThependingthreadswillqueueinorderofpriority. 25* 26*RT_IPC_FLAG_FIFOThependingthreadswillqueueinthefirst-in-first-outmethod 27*(alsoknownasfirst-come-first-served(FCFS)schedulingstrategy). 28* 29*NOTE:RT_IPC_FLAG_FIFOisanon-real-timeschedulingmode.Itisstronglyrecommendedto 30*useRT_IPC_FLAG_PRIOtoensurethethreadisreal-timeUNLESSyourapplicationsconcernabout 31*thefirst-in-first-outprinciple,andyouclearlyunderstandthatallthreadsinvolvedin 32*thiseventwillbecomenon-real-timethreads. 33* 34*@returnReturntheoperationstatus.WhenthereturnvalueisRT_EOK,theinitializationissuccessful. 35*Ifthereturnvalueisanyothervalues,itrepresentstheinitializationfailed. 36* 37*@warningThisfunctioncanONLYbecalledfromthreads. 38*/ 39rt_err_trt_event_init(rt_event_tevent,constchar*name,rt_uint8_tflag) 40{ 41… 42}

9.缩进及分行

缩进请采用 4 个空格的方式。如果没有什么特殊意义，请在 “{” 后进行分行，并在下一行都采用缩进的方式，例如：

复制1if(condition) 2{ 3/*others*/ 4}

唯一的例外是 switch 语句，switch-case 语句采用 case 语句与 switch 对齐的方式，例如：

复制1switch(value) 2{ 3casevalue1: 4break; 5}

case 语句与前面的 switch 语句对齐，后续的语句则采用缩进的方式。分行上，如果没有什么特殊考虑，请不要在代码中连续使用两个以上的空行。

10.大括号与空格

从代码阅读角度，建议每个大括号单独占用一行，而不是跟在语句的后面，例如：

复制1if(condition) 2{ 3/*others*/ 4}

匹配的大括号单独占用一行，代码阅读起来就会有相应的层次而不会容易出现混淆的情况。空格建议在非函数方式的括号调用前留一个空格以和前面的进行区分，例如：

复制1if(x<= y) 2{ 3/*others*/ 4} 5 6for(index=0;index< MAX_NUMBER; index ++) 7{ 8/*others*/ 9}

建议在括号前留出一个空格(涉及的包括 if、for、while、switch 语句)，而运算表达式中，运算符与字符串间留一个空格。另外，不要在括号的表达式两侧留空格，例如：

复制1if(x<= y ) 2{ 3/*other*/ 4}

这样括号内两侧的空格是不允许的。

11.trace、log信息

在 RT-Thread 中，普遍使用的 log 方式是 rt_kprintf。rt_kprintf 在 RT-Thread 被实现成一个采用轮询、非中断方式的字串输出，能够适合于在中断这类”即时”显示日志的场合。因为这种轮询方式的存在，也必然会影响到日志输出的时序关系。

建议在代码中不要频繁的使用 rt_kprintf 作为日志输出，除非你真正的明白，你的代码运行占用的时间多一些也没什么关系。

日志输出应该被设计成正常情况下是关闭状态(例如通过一个变量或宏就能够开启)，并且当真正输出日志时，日志是易懂易定位问题的方式。”天书式”的日志系统是糟糕的，不合理的。

12.函数

在内核编程中，函数应该尽量精简，仅完成相对独立的简单功能。函数的实现不应该太长，函数实现太长，应该反思能够如何修改(或拆分)使得函数更为精简、易懂。

13.对象

RT-Thread 内核采用了 C 语言对象化技术，命名表现形式是：对象名结构体表示类定义、对象名 + 动词短语形式表示类方法，例如：

复制1structrt_timer 2{ 3structrt_objectparent; 4/*otherfields*/ 5}; 6typedefstructrt_timer*rt_timer_t;

结构体定义 rt_timer 代表了 timer 对象的类定义；

复制1rt_timer_trt_timer_create(constchar*name, 2void(*timeout)(void*parameter), 3void*parameter, 4rt_tick_ttime,rt_uint8_tflag); 5rt_err_trt_timer_delete(rt_timer_ttimer); 6rt_err_trt_timer_start(rt_timer_ttimer); 7rt_err_trt_timer_stop(rt_timer_ttimer);

rt_timer + 动词短语的形式表示能够应用于 timer 对象的方法。

在创建一个新的对象时，应该思考好，对象的内存操作处理：是否允许一个静态对象存在，或仅仅支持从堆中动态分配的对象。

14.格式化代码

格式化代码是指通过脚本自动整理你的代码，并使其符合 RT-Thread 的编码规范。本文提供以下两种自动格式化代码方法，可以自行选择或配合使用。

使用 astyle 格式化

用 astyle 自动格式化代码，参数如下：

复制 1–style=allman 2–indent=spaces=4 3–indent-preproc-block 4–pad-oper 5–pad-header 6–unpad-paren 7–suffix=none 8–align-pointer=name 9–lineend=linux 10–convert-tabs 11–verbose

能满足函数空格、缩进、函数语句等的规范。