让代码会说话
📎 嵌入式C注释规范 · 30章
01
注释的本质：为什么说注释是写给人的，不是写给机器的？代码即文档的误区。
人与机器 · 文档误区
02
文件头注释：版权信息、文件功能描述、修改历史记录的标准化写法。
版权 · 功能 · 修改历史
03
函数头注释：功能描述、参数说明、返回值说明、注意事项的规范模板。
函数 · 参数 · 返回值
04
单行注释的艺术：什么时候该用//，什么时候不该用，避免过度注释。
// 艺术 · 避免过度
05
多行注释的陷阱：/* */ 的嵌套问题、Doxygen风格与普通多行注释的选择。
嵌套陷阱 · Doxygen风格
06
行尾注释：变量声明、简短逻辑后的注释技巧，对齐与不对齐的争论。
行尾技巧 · 对齐争论
07
TODO与FIXME：临时注释的标准化管理，如何避免技术债务。
TODO · FIXME · 技术债务
08
Doxygen入门：安装配置、常用标签（@brief, @param, @return）的使用。
Doxygen · 标签入门
09
Doxygen进阶：@note, @warning, @see, @deprecated 等高级标签实战。
高级标签 · 实战
10
注释与宏定义：#define 的注释规范，函数宏与普通宏的区别注释。
宏定义 · 函数宏
11
注释与枚举：枚举值的含义注释，位掩码枚举的注释技巧。
枚举 · 位掩码
12
注释与结构体：成员变量的注释规范，对齐注释提升可读性。
结构体 · 对齐注释
13
注释与全局变量：extern 变量的注释，全局状态机的注释策略。
全局变量 · 状态机
14
注释与回调函数：函数指针类型的注释，回调语义的文档化。
回调 · 函数指针
15
注释与硬件寄存器：寄存器位定义的注释规范，地址映射的注释。
寄存器 · 地址映射
16
注释与中断服务程序：ISR 的注释要点，临界区的注释标记。
ISR · 临界区
17
注释与断言：assert 的注释，前置条件与后置条件的文档化。
断言 · 前置/后置条件
18
注释与日志：调试日志的注释规范，日志级别的注释说明。
调试日志 · 级别
19
注释与版本控制：Git提交信息中的注释规范，ChangeLog的编写。
Git · ChangeLog
20
注释与代码审查：Reviewer注释的格式，CR反馈的文档化。
代码审查 · CR反馈
21
注释与单元测试：测试用例的注释，Mock函数的注释规范。
单元测试 · Mock
22
注释与配置表：配置参数的注释，默认值的注释说明。
配置表 · 默认值
23
注释与状态机：状态转移图的注释，状态处理函数的注释。
状态机 · 转移图
24
注释与协议栈：协议字段的注释，报文解析的注释技巧。
协议栈 · 报文解析
25
注释与算法：复杂算法的步骤注释，时间复杂度的注释。
算法步骤 · 时间复杂度
26
注释与平台移植：平台相关代码的注释，条件编译的注释策略。
平台移植 · 条件编译
27
注释与安全关键：MISRA-C 对注释的要求，安全相关注释的强制规范。
MISRA-C · 安全强制
28
注释与代码生成：自动生成代码的注释，手工代码与生成代码的注释区分。
代码生成 · 手工区分
29
注释与团队协作：团队注释规范的制定，Code Review中的注释文化。
团队规范 · CR文化
30
注释的未来：AI辅助注释生成，注释与文档自动化的趋势。
AI辅助 · 自动化趋势
✨ 每一行注释，都是对未来的承诺 ✨