编码规范
- 开始日期:2023-03-26
- 目标主要版本:3.x
- 参考问题:无
- 实现 PR:无
概要
参考其它 C 开源项目,重新制定统一的编码规范。
基本示例
typedef enum parser_state_t {
PARSER_STATE_START,
PARSER_STATE_DATA_BEGIN,
PARSER_STATE_DATA_END,
PARSER_STATE_ERROR
} parser_state_t;
typedef struct parser_t {
/** 解析器状态 */
parser_state_t state;
/** 当前字符 */
char *cur;
} parser_t;
parser_t *parser_create(void)
{
parser_t *parser;
parser = malloc(sizeof(parser_t));
parser->state = PARSER_STATE_START;
parser->cur = NULL;
return parser;
}
动机
2.x 版本的代码风格不一致,包含了驼峰、小写下划线风格以及各种命名规则,导致源码阅读体验和接口使用体验较差。
详细设计
使用 clang-format 工具对源码进行格式化,其配置文件 .clang-format
存放于源码根目录中。
由于预设的格式化规则已经满足此编码 规范的大部分要求,以下仅对需要在编码时注意的规范进行简单说明,不再详细说明规范的全部内容。
命名
常见的 C 语言开源库的编码风格大都是蛇形命名法(snake_case
),例如:libgit2、cairo、leveldb,因此,LCUI 项目也采用该编码风格。
由于 LCUI 已被拆分为多个子库,这些库内的标识符不再需要添加 LCUI_
前缀。
类型名以 _t
结尾,例如:
typedef struct foo_t {
int bar;
} foo_t;
宏定义和枚举采用大写下划线命名法,例如:
typedef enum pd_color_type_t {
PD_COLOR_TYPE_INDEX8,
PD_COLOR_TYPE_GRAY8,
PD_COLOR_TYPE_RGB323,
PD_COLOR_TYPE_ARGB2222,
PD_COLOR_TYPE_RGB555,
PD_COLOR_TYPE_RGB565,
PD_COLOR_TYPE_RGB888,
PD_COLOR_TYPE_ARGB8888
} pd_color_type_t;
#define PANDAGL_VERSION "0.1.0"
注释
推荐写在代码行上面:
struct foo {
/** comment */
int bar;
/** string */
char *str;
}
不推荐写在右侧:
struct foo {
int bar; /**< comment */
char *str; /**< string */
}
缩进
为确保代码在网页端和编辑器内的显示效果一致,以八个空格为一个缩进层级,不使用制表符缩进。
缺点
改动很大,涉及几 乎所有代码,从 2.x 版本迁移到 3.x 版本需要参照头文件内容对旧的标识符进行全局替换。
备选方案
全部采用驼峰命名。