xf_template 编程风格模板。更多...

#include "xf_template_header_detail.h"
#include "xf_component_template.h"
#include "xf_utils.h"

xf_template_source_detail.c 的引用(Include)关系图:

结构体
struct	_xf_templ_struct_t
	结构体示例。更多...

宏定义
#define	XF_TEMPLATE_HELP_STR "xf_template v0.1"
	关于格式化程序。

#define	XF_TEMPLATE_HELP_STR_SPLICING "test" XF_TEMPLATE_HELP_STR "abc123"

#define	XF_TEMPLATE_DEFINE (1)

#define	XF_TEMPLATE_MACROS_ADD(_a, _b) ((_a) + (_b))
	带参宏: [Macros].

#define	XF_TEMPLATE_MACROS_NO_RETURN(_a, _b)
	无需返回参数的宏。

#define	XF_TEMPLATE_MACROS_HAS_RETURN(_x)
	需要返回参数的宏。

#define	XF_TEMPL_PRINTF(_fmt, ...)
	关于条件编译。

#define	UNUSED(_x) ((void)(_x))

类型定义
typedef enum _xf_templ_enum_t	xf_templ_enum_t
	类型定义: [Typedefs].

typedef int	xf_templ_int_t

typedef struct _xf_templ_struct_t	xf_templ_struct_t
	结构体示例。

枚举
enum	_xf_templ_enum_t { XF_TEMPL_ENUM_0 = 0x00 , XF_TEMPL_ENUM_1 , XF_TEMPL_ENUM_2 , XF_TEMPL_ENUM_MAX , XF_TEMPL_ENUM_DEFAULT = XF_TEMPL_ENUM_1 }
	类型定义: [Typedefs]. 更多...

函数
static xf_templ_int_t	_xf_template_func (xf_templ_struct_t p_struct, int32_t p_out)
	静态函数原型: [Static Prototypes].

void	a_function_of_very_many_parameters (uint32_t a_parameter_with_a_very_long_name, uint32_t another_parameter_with_a_very_long_name, uint32_t a_parameter_with_a_very_long_name_too, uint32_t a_parameter_with_a_very_long_name_that_is_really_long)
	一个演示函数参数换行的示例。

void	xf_main (void)
	全局函数定义: [Global Functions].

xf_templ_err_t	xf_template_init (void)
	一个初始化函数。

变量
static const char *const	TAG = "xf_main"
	静态变量: [Static Variables].

static xf_templ_int_t	s_data = 0

static xf_templ_struct_t	s_struct = {0}

static void *	p_a_pointer = NULL

int	g_xf_templ_global_data1_in_head = 0
	全局变量: [Global Variables].

int	g_xf_templ_global_data2_no_in_head = 0

详细描述

xf_template 编程风格模板。

作者: 你的名字 (你的邮箱@.nosp@m.doma.nosp@m.in.co.nosp@m.m)

每行字数限制

建议每行**少于 80 个字符**，这样在 vscode 中分两栏也可以看全部代码。 123456789012345678901234567890123456789012345678901234567890123456789012345678 代码正文最长不要超过 120 字符。
注释

2.1 中文与英文、数字之间根据需要加空格。例如：
1. 你说的对，但是《STM32》是由意法半导体 (ST) 推出的一系列 32 位的单片机。
2. 在 windows 10, 1080p, 缩放 125 %, vscode 默认的缩放的情况下。
缩进

代码中使用 4 个空格作为缩进，不要使用 TAB。
行尾

不要在行尾尾随空格。
大括号

只有函数定义的左大括号必须换行，在函数中的左大括号不需要换行（K&R风格）。

版本: 1.0

日期: 2023-10-23

版权所有: Copyright (c) 2023

参见

在文件 xf_template_source_detail.c 中定义.

宏定义说明

◆ XF_TEMPLATE_HELP_STR

#define XF_TEMPLATE_HELP_STR "xf_template v0.1"

关于格式化程序。

基于 esp-idf 的格式化风格修改。

参见: esp-idf/tools/format.sh: https://github.com/espressif/esp-idf/blob/v5.0/tools/format.sh

注解: 安装 Astyle 应用程序以及 vscode 插件后，在 vscode 的 setting.json 中添加：
"astyle.cmd_options": [

"--indent=spaces=4",

"--attach-namespaces",

"--attach-classes",

"--pad-oper",

"--pad-header",

"--unpad-paren",

"--unpad-brackets",

"--squeeze-lines=1",

"--align-pointer=name",

"--align-reference=name",

"--keep-one-line-statements",

"--convert-tabs",

"--max-code-length=120"

],

// xfusion 提供了 astyle-3.4.12: xfusion/tools/format_code/astyle/astyle-3.4.12-linux-x64

"astyle.executable": "astyle", ///< 修改为你的 astyle 可执行文件的路径

注意填写 Astyle 可执行文件路径到 vscode 中。

一些说明。

注解: **不要**用"///"的 doxygen 注释格式，此处使用是因为注释中需要包含多行注释。

1. 内容标识：用于指示以下区域应当填写什么内容。

如： /* ==================== [Includes] ========================================== ‍/ / ==================== [Defines] =========================================== *‍/

注意： 1.1 内容标识中，从开头到'['（不含）共有 24 个字符。 /* ==================== 1.2 内容标识中，从开头到末尾共有 80 个字符，编程时尽量不要超过内容标识的长度。 1.3 如需更改 "[]" 内的内容，请增删 ']' 右侧的 '='，使总长度维持 80 字符。 1.4 内容标识的顺序**不建议更改**。

2. 代码与内容标识之间要有一个空白换行的间隔。

                             /* 此行空白换行 */
/* ==================== [Includes] ========================================== */
                             /* 此行空白换行 */
#include <stdio.h>
                             /* 此行空白换行 */
/* ==================== [Defines] =========================================== */
                             /* 此行空白换行 */
#define XF_TEMPLATE_DEFINE              (1)
                             /* 此行空白换行 */

3. 如果注释中只有一句 brief，注意删除后面的空行。如：

/‍**

我是注释。 *‍/ /‍**
不要这样，下面的空行意义不明的。
*‍/

头文件: [Includes].

在这里放头文件，通常顺序是：

当前组件的公共头文件；如：#include "xf_template_header_detail.h"；
标准库，如 #include <stdio.h>；
其他 POSIX 标准标头，如：#include <sys/time.h>；
本文件所需要的其他组件的头文件，如：#include "xf_log.h"、#include "xf_spi.h"；
本文件所需要的当前组件的其他头文件或者私有头文件。

参见: https://docs.espressif.com/projects/esp-idf/zh_CN/v5.1/esp32/contribute/style-guide.html#include-statements

宏定义(无参宏): [Defines].

一般建议加括号。
不强制要求对齐，除非代码已经稳定很少更改。

在文件 xf_template_source_detail.c 第 152 行定义.

◆ XF_TEMPLATE_HELP_STR_SPLICING

#define XF_TEMPLATE_HELP_STR_SPLICING "test" XF_TEMPLATE_HELP_STR "abc123"

在文件 xf_template_source_detail.c 第 153 行定义.

◆ XF_TEMPLATE_DEFINE

#define XF_TEMPLATE_DEFINE (1)

在文件 xf_template_source_detail.c 第 154 行定义.

◆ XF_TEMPLATE_MACROS_ADD

#define XF_TEMPLATE_MACROS_ADD	(	_a,
		_b
	)	((_a) + (_b))

带参宏: [Macros].

与宏定义（[Defines]）的区别是是否有参数（不严格区分）。
宏中参数通常建议以下划线开头，以区别于普通变量。
宏参数在使用时通常加以括号，防止表达式传入宏参数时造成逻辑错误。
宏如果需要多行，不要求对齐继续符"\"。

带参宏示例。

在文件 xf_template_source_detail.c 第 291 行定义.

◆ XF_TEMPLATE_MACROS_NO_RETURN

#define XF_TEMPLATE_MACROS_NO_RETURN	(	_a,
		_b
	)

值:

    do { \
        s_data = (_a) + (_b); \
    } while (0)

无需返回参数的宏。

通常需要用 do { } while (0) 包围（除非通过宏定义变量等情况）。
while (0) 后不要加分号（使用时强制加分号）。

在文件 xf_template_source_detail.c 第 299 行定义.

◆ XF_TEMPLATE_MACROS_HAS_RETURN

#define XF_TEMPLATE_MACROS_HAS_RETURN ( _x )

值:

    ({                                      \
        typeof(_x) __ret = (_x);            \
        __ret = __ret + (_x);               \
        (__ret);                            \
    })

需要返回参数的宏。

使用 ({ }) 包围。
明显括出返回值。

在文件 xf_template_source_detail.c 第 310 行定义.

◆ XF_TEMPL_PRINTF

#define XF_TEMPL_PRINTF	(	_fmt,
		...
	)

关于条件编译。

需要在对应的 #else 后追加相应的的条件（如：!defined(xf_log_printf)），在 #endif 后标注 #if 的信息（如：defined(xf_log_printf)）。

注解: 如何宏需要缩进保持美观，请在'#'号后面缩进。如下缩进所示。

在文件 xf_template_source_detail.c 第 329 行定义.

◆ UNUSED

#define UNUSED ( _x ) ((void)(_x))

未使用的变量

示例: examples/peripherals/adc/adc_base/main/xf_main.c, examples/peripherals/dac/wave_gen/main/xf_main.c, examples/peripherals/gpio/input_output/main/xf_main.c, examples/peripherals/i2c/i2c_master_half_duplex/main/xf_main.c, examples/peripherals/i2c/i2c_slave_half_duplex/main/xf_main.c, examples/peripherals/spi/spi_master_half_duplex/main/xf_main.c, examples/peripherals/spi/spi_slave_half_duplex/main/xf_main.c, examples/peripherals/timer/timer_base/main/xf_main.c, examples/peripherals/uart/uart_echo/main/xf_main.c, examples/peripherals/uart/uart_rx_tx_task/main/xf_main.c, examples/protocols/http_request/main/xf_main.c, examples/protocols/icmp_echo/main/xf_main.c, examples/protocols/iperf/softap/main/xf_main.c, examples/protocols/iperf/station/main/xf_main.c, examples/protocols/sockets/tcp_client/main/xf_main.c, examples/protocols/sockets/tcp_server/main/xf_main.c, examples/protocols/sockets/udp_client/main/xf_main.c, examples/protocols/sockets/udp_server/main/xf_main.c, examples/storage/fal/fal_flashdb/main/xf_main.c, examples/wireless/ble/sample_gatt_client/main/xf_main.c, examples/wireless/ble/sample_gatt_server/main/xf_main.c, examples/wireless/wifi/get_started/softap/main/xf_main.c, examples/wireless/wifi/get_started/station/main/xf_main.c, examples/wireless/wifi/scan/base_scan/main/xf_main.c, examples/wireless/wifi/scan/scan_and_connect/main/xf_main.c, examples/wireless/wifi/static_ip/softap/main/xf_main.c , 以及 examples/wireless/wifi/static_ip/station/main/xf_main.c.

在文件 xf_template_source_detail.c 第 333 行定义.

类型定义说明

◆ xf_templ_enum_t

typedef enum _xf_templ_enum_t xf_templ_enum_t

类型定义: [Typedefs].

类型定义的类型**必须**以_t为结尾。前缀xf_表示是在 xf_hal 中定义的。

枚举类型示例。

枚举类型通过类型定义重命名。
枚举类型命名是类型定义名字前加单下划线。如 "_xf_templ_enum_t"。用 xf_templ_enum_e 也可以。
枚举类型的值需要大写。
枚举值通常要求有一个最大值，并且该最大值通常不作为正常值使用。

◆ xf_templ_int_t

typedef int xf_templ_int_t

"!<"表示当前的注释的说明对象是前面的代码，没有的话默认都是说明后面的代码。

在文件 xf_template_source_detail.c 第 183 行定义.

◆ xf_templ_struct_t

typedef struct _xf_templ_struct_t xf_templ_struct_t

结构体示例。

结构体**必须**用类型定义。
结构体名字是类型定义名字前加单下划线。如：_xf_templ_struct_t。当然用 xf_templ_struct_s 也可以。

枚举类型说明

◆ _xf_templ_enum_t

enum _xf_templ_enum_t

类型定义: [Typedefs].

类型定义的类型**必须**以_t为结尾。前缀xf_表示是在 xf_hal 中定义的。

枚举类型示例。

枚举类型通过类型定义重命名。
枚举类型命名是类型定义名字前加单下划线。如 "_xf_templ_enum_t"。用 xf_templ_enum_e 也可以。
枚举类型的值需要大写。
枚举值通常要求有一个最大值，并且该最大值通常不作为正常值使用。

枚举值
XF_TEMPL_ENUM_0	枚举值 0，第一个枚举值要求手动赋值
XF_TEMPL_ENUM_1	枚举值 1
XF_TEMPL_ENUM_2	枚举值 2
XF_TEMPL_ENUM_MAX	枚举值最大值
XF_TEMPL_ENUM_DEFAULT	枚举值默认值

在文件 xf_template_source_detail.c 第 173 行定义.

函数说明

◆ _xf_template_func()

static xf_templ_int_t _xf_template_func	(	xf_templ_struct_t *	p_struct,
		int32_t *	p_out
	)

static

静态函数原型: [Static Prototypes].

只在当前文件内可以调用的函数，通常建议函数名前加**单下划线**。
注意在此处添加静态函数的说明注释。

一个静态函数。（说明注释）

参数

	p_struct	输入一个的结构体。参数默认都是输入，可以不标记[in]，
[out]	p_out	指向用于传出数据的指针（会改变原本的变量）。需要传出的参数注释时添加[out]。

返回

xf_templ_int_t 返回一个返回值。

(XF_TEMPL_FAIL) 出错了
(other) 不值得注意的返回值

注解: 函数如果需要传出，那么传出的参数应当放在后面。

< goto 通常用作出错后处理。

单字节变量通常只能用作循环变量。

< 记录返回值

< 注意 label 前面要有单下划线

在文件 xf_template_source_detail.c 第 422 行定义.

◆ a_function_of_very_many_parameters()

void a_function_of_very_many_parameters	(	uint32_t	a_parameter_with_a_very_long_name,
		uint32_t	another_parameter_with_a_very_long_name,
		uint32_t	a_parameter_with_a_very_long_name_too,
		uint32_t	a_parameter_with_a_very_long_name_that_is_really_long
	)

一个演示函数参数换行的示例。

参数

a_parameter_with_a_very_long_name	无用参数。
another_parameter_with_a_very_long_name	无用参数。
a_parameter_with_a_very_long_name_too	无用参数。
a_parameter_with_a_very_long_name_that_is_really_long	无用参数。