s_dev_guidelines 开源项目分析目录摘要一、项目概览二、核心文档逐一解析三、三份规范的协同关系工程闭环四、整体设计特点与亮点五、适用场景与落地建议六、总结一、项目概览1.1 项目定位项内容项目名称Dev Guidelines — 软件开发规范集仓库地址https://gitee.com/smallerxuan/s_dev_guidelines项目性质纯文档型仓库无代码、无构建系统适用范围通用库、应用程序、服务、嵌入式固件等各类软件项目开源协议CC BY 4.0知识共享署名允许商用与修改需署名1.2 仓库结构s_dev_guidelines/ ├── README.md # 项目说明收录文档、特点、用法、Roadmap ├── C语言代码编写规范.md # 13 章 C 编码规范 ├── Git 提交信息规范.md # Conventional Commits 指南 ├── Git 分支管理规范.md # 精简版 Git Flow └── LICENSE # CC BY 4.0 许可证全文1.3 规范基准三份文档各自锚定业界公认基准而非凭空自创文档规范基准本地化取舍C 语言代码编写规范Linux Kernel Style GNU Coding Standards缩进改为 4 空格Kernel 原版为 Tab禁用stdbool.hGit 提交信息规范Conventional Commits v1.0.0subject 允许中文祈使句scope 列表留待项目自定义Git 分支管理规范Git Flow / GitHub Flow精简 可裁剪LTS、variant 均为可选层二、核心文档逐一解析2.1 《C 语言代码编写规范》13 章这是三份文档中体量最大的一份覆盖 C 项目编码的完整生命周期。章节结构章节主题核心规则1命名规范小写下划线为主风格prv_前缀表 static 私有函数禁驼峰、禁匈牙利命名、禁单字母变量2格式化与排版4 空格缩进禁 TabKR(1TBS) 大括号行宽 80/120单行if必须带大括号3文件组织源文件 8 段式结构文件头→include→宏→类型→全局→静态→原型→实现include/src/tests/docs目录建议4数据类型强制stdint.h定宽类型size_t表长度禁止用 typedef 隐藏 struct5变量与常量就近声明、最小作用域、一行一声明、声明即初始化全局变量加g_前缀并尽量static6函数设计单页原则50–80 行嵌套 ≤3–4 层输入参数在前输出在后错误码用负值枚举7指针与内存int *p星号靠变量指针显式! NULL比较free 后置空禁用 VLA8宏与预处理宏全大写加项目前缀参数必须加括号多语句宏用do-while(0)优先 inline 函数替代9注释规范Doxygen 风格文件头/函数注释brief/param/retval/warningTODO/FIXME/HACK 标记10错误处理负值错误码枚举早期返回与goto集中清理两种模式assert 与运行时检查分工11头文件管理最小包含、自包含、前向声明优先#ifndef保护或#pragma onceextern C兼容12编译与构建-Wall -Wextra -Werror基线 9 个增强警告新项目用 C11列明 clang-tidy/cppcheck/sparse13代码审查清单10 项 Checklist 完整 ring_buffer 示范代码附录.clang-format完整配置可直接落盘使用、8 组常见错误对照表。值得注意的取舍与 Kernel Style 的差异缩进用 4 空格而非 TabLinux Kernel 原版要求 Tab8 字符宽此处明确改为 4 空格更贴近嵌入式厂商 SDK 与现代团队习惯布尔值用uint8_t 0/1不用stdbool.h规避部分老旧嵌入式工具链的兼容问题属于面向受限平台的保守选择禁止 typedef 隐藏 struct与 Kernel Style 一致保持类型透明便于追踪内存布局——这对需要关注对齐、大小的嵌入式场景尤为重要。2.2 《Git 提交信息规范》8 章基于 Conventional Commits v1.0.0 的完整中文化落地指南。核心格式type(scope): subject body footer要点结构部分内容type 类型表11 种类型feat/fix/docs/style/refactor/perf/test/chore/ci/build/revert并标注各自触发的 SemVer 级别scope 作用域提供 11 个通用 scope 参考core/api/net/parser/deps…明确各项目应自定义 scope 列表subject 规则祈使句现在时、≤50 字符、末尾无句号附 ❌/✅ 对照body/footerbody 解释为什么而非是什么footer 承载Closes #xxx、BREAKING CHANGE:、Co-authored-by:完整示例新功能、Bug 修复、破坏性变更三个带上下文的真实示例特殊场景Merge Commit、revert、WIP含[skip ci]用法工具链commitlint 完整配置含 scope-enum、header-max-length 等 6 条规则、husky 钩子、pre-commit/Lefthook 跨语言替代SemVer 映射BREAKING CHANGE→MAJOR、feat→MINOR、fix→PATCH其余不升版设计亮点没有把 scope 列表写死而是将其定位为项目预留扩展点并在 commitlint 配置的注释中明确提示按项目模块调整——这与整套规范通用版 项目裁剪的总设计哲学一致。2.3 《Git 分支管理规范》10 章以精简版 Git Flow为基线的分支模型是三份文档中架构性最强的一份。模型选型第 1 章先横向对比 Git Flow / GitHub Flow / GitLab Flow / Trunk-based 四种主流模型再给出选型结论——保留main/develop双长期分支 feature/release/hotfix三类短期分支。分支职责第 3 章核心分支性质检出源合并目标关键约束main长期——仅存已发布版本每个合并点打 SemVer 标签禁止直接提交develop长期——允许已知缺陷但须通过编译冒烟版本号加-dev后缀feature/*短期developdevelop一功能一分支超 2 周须拆分禁止混更依赖版本release/v*短期developmaindevelop冻结新功能支持-rcN候选轮次hotfix/*短期main标签maindevelop优先级最高必须验证双侧包含相同修复main-v*.x长期可选main标签—LTS 维护只收 hotfix 不收 featurevariant/*长期可选maincherry-pick 回流多平台/多客户变体优先推荐条件编译替代chore/*短期developdevelop依赖升级等杂项独立分支合并策略第 4 章Rebase vs Merge 决策表是亮点——本地同步用 rebase 保持线性、合入 develop 用--no-ff保留功能节点、已推送公共分支绝对禁止 rebase/amend。分支保护第 5 章给出可直接照抄的服务端配置矩阵main需 2 人审查 全量 CI、develop需 1 人审查 编译检查等及 GitLab 配置示例。延伸章节第 6 章通用项目管理构建产物命名规范{project}_v{x.y.z}_{variant}_{date}.{ext}、submodule 更新流程、密钥与配置分离第 7 章仓库组织Monorepo vs Polyrepo 决策表推荐Monorepo 分目录隔离并附目录树第 8 章快速决策流程图开始新功能/紧急修复/依赖升级/发布四条路径附录分支生命周期速查表、常用命令速查、版本号与分支对应关系图。嵌入式特色LTS 分支对应已交付固件的长期维护与 variant 分支对应多硬件平台/客户定制是典型嵌入式诉求但文档同时强调优先用条件编译/分目录隔离替代变体分支避免了分支碎片化——这个取舍说明体现了对实际工程复杂度的清醒认识。三、三份规范的协同关系工程闭环三份文档不是孤立堆砌而是构成一条从单次提交到正式发布的完整链路feat/fix 提交提交规范 │ type 决定 SemVer 级别 ▼ 版本号递增 v{MAJOR}.{MINOR}.{PATCH}提交规范 附录B │ release 分支合并到 main 时打标签 ▼ main 上的语义化标签分支规范 3.1 │ 标签触发 CI ▼ 发布产物 自动 CHANGELOG分支规范 6.1 git-cliff │ ▼ C 代码本身的质量由编码规范 Code Review Checklist 兜底具体咬合点scope 一致性分支规范中 feature 分支命名feature/{scope}-{description}与提交规范的 scope 概念同源模块名贯穿分支名与提交信息SemVer 贯穿提交规范的 type→SemVer 映射正是分支规范中main打v{x.y.z}标签、hotfix升 PATCH 的依据质量门禁互补C 规范的编译警告基线-Werror与 Review Checklist恰好对应分支保护策略中的CI 全量测试通过和PR 审查要求依赖管理呼应提交规范的chore(deps):类型对应分支规范中依赖升级必须走独立chore/update-*分支、禁止在 feature 中混更。四、整体设计特点与亮点4.1 结构化程度高每份文档统一采用对照表格 速查卡 Checklist三件套。表格承担可查职能Checklist 承担可执行职能速查卡承担可记忆职能——三者分别对应 Code Review、提交前自检、日常查阅三种使用场景。4.2 正误示例对照关键规则均有 ❌/✅ 对照命名、指针声明、提交信息 subject、宏括号等比纯文字规则的学习成本低得多。C 规范末尾还给出一份 700 行级的完整 ring_buffer 示范模块把文件头、错误码、assert、内存管理全套规则串了一遍。4.3 规则 理由 何时可简化三段式不只给规则还说明为什么以及何时可以放松单人项目可简化为 GitHub Flow分支规范 3.8变体分支优先用条件编译替代分支规范 3.7单人项目 PR 审查可豁免分支规范 4.1。这种有取舍说明的写法避免了规范沦为教条。4.4 工具链配置开箱即用.clang-format、commitlint.config.js、husky 钩子、GitLab 分支保护配置均可直接复制落地且文档间互相指引如 README 的团队落地建议直接指向分支规范第五章。4.5 通用版 预留扩展点所有项目相关变量scope 列表、变体命名、目录结构都显式标注为按项目实际调整文档末尾统一预留了各项目可增补私有约定的说明二次采纳的摩擦很小。五、适用场景与落地建议5.1 适用性评估场景适配度说明嵌入式固件团队★★★★★C 规范面向受限平台做了取舍禁 VLA、禁 stdbool、定宽类型LTS/variant 分支直击多平台维护痛点通用 C/C 库开发★★★★★头文件管理、错误码设计、错误处理两模式直接可用小团队/个人项目★★★★☆提供了简化模型与审查豁免可低门槛起步大型 Trunk-based 团队★★☆☆☆基线模型是 Git Flow与高频集成的主干开发模式取向不同非 C 语言项目★★★☆☆Git 两份规范完全通用C 规范仅命名/格式化思路可参考5.2 推荐的采纳路径第一步成本最低采纳《Git 提交信息规范》配 commitlint 钩子一周即可全员生效第二步采纳《Git 分支管理规范》并在 Git 服务端配置分支保护第五章表格可直接照抄第三步以《C 语言代码编写规范》附录的.clang-format统一存量代码格式再在 CI 加入警告基线第四步按项目实际增补 scope 列表、变体命名等私有约定形成项目版规范。六、总结s_dev_guidelines 是一套完成度较高的中文工程规范集。其核心价值不在单条规则的创新规则均有成熟出处而在于三点体系化编码、提交、分支三个环节不是孤立的而是通过 SemVer、scope、CI 门禁互相咬合形成完整工程闭环可落地每条规则配理由、每个章节配速查、每个工具配配置拿去即用有取舍明确标注何时可以简化、何处留给项目自定义避免了规范常见的教条化问题。
