|
|
我是老温，一名热爱学习的嵌入式工程师9 f6 R( T! v( n- Q) b" E
关注我，一起变得更加优秀！* J/ T/ Q* p% M' W+ G
相信各位工程师大佬一定遇到过这种情况：领导甩给你一个项目的源码让你阅读，你尝试理解并重构代码，但里面一句注释都没有，心中难免会想，这肯定是之前同事“删库跑路”了。更悲催的是，虽然有注释，但大部分的注释都与代码不符，或者存在大量的无效注释和无效代码块。
* {7 b+ i$ R, e, m9 @, U什么因素对于阅读一份源码至关重要？除了遵循各种编码规范之外，还有一个比较重要的，就是注释规范。工程师不喜欢写注释和文档，工程师不喜欢别人不写注释和文档，注释虽然写起来很痛苦, 但对保证代码可读性至关重要，下面的将描述如何注释以及在哪儿注释。) V9 s1 d9 x* m
1、注释风格 1.总述一般使用 // 或 /* */，只要统一就好。. e; F) L7 X. p# k) d3 }+ D3 K: U$ ~
2.说明
2 Q7 w. e F/ p. D6 E// 或 /* */ 都可以，但 // 更 常用，要在如何注释及注释风格上确保统一。. W4 i$ l$ Z5 G- Q3 i
2、文件注释1.总述在每一个文件开头加入版权、作者、时间等描述。文件注释描述了该文件的内容，如果一个文件只声明，或实现，或测试了一个对象，并且这个对象已经在它的声明处进行了详细的注释，那么就没必要再加上文件注释，除此之外的其他文件都需要文件注释。2.说明法律公告和作者信息：每个文件都应该包含许可证引用. 为项目选择合适的许可证版本(比如, Apache 2.0, BSD, LGPL, GPL)。如果你对原始作者的文件做了重大修改，请考虑删除原作者信息。3.文件内容如果一个 .h 文件声明了多个概念, 则文件注释应当对文件的内容做一个大致的说明, 同时说明各概念之间的联系. 一个一到两行的文件注释就足够了, 对于每个概念的详细文档应当放在各个概念中, 而不是文件注释中。" H4 u/ c- h/ ~! O O" |
不要在 .h 和 .cc 之间复制注释, 这样的注释偏离了注释的实际意义。
3 ~4 {1 P) q/ @4 F, D N/ d3、函数注释 1.总述函数声明处的注释描述函数功能; 定义处的注释描述函数实现。2.说明函数声明：基本上每个函数声明处前都应当加上注释, 描述函数的功能和用途. 只有在函数的功能简单而明显时才能省略这些注释(例如, 简单的取值和设值函数)。比如：FreeRTOS创建任务函数申明：: ]$ D1 e/ L/ ]4 q
0cxrr4ni41164067201509.png
) X! n( I a- D" }
函数定义： \+ e; _- n( z3 v8 U' k9 q
如果函数的实现过程中用到了很巧妙的方式, 那么在函数定义处应当加上解释性的注释。比如, 你所使用的编程技巧, 实现的大致步骤, 或解释如此实现的理由. 举个例子, 你可以说明为什么函数的前半部分要加锁而后半部分不需要。不要 从 .h 文件或其他地方的函数声明处直接复制注释. 简要重述函数功能是可以的, 但注释重点要放在如何实现上。
, o" e) M5 B% z' C- [ C4、变量注释1.总述通常变量名本身足以很好说明变量用途， 某些情况下, 也需要额外的注释说明。2.说明根据不同场景、不同修饰符，变量可以分为很多种类，总的来说变量分为全局变量、局部变量。一般来说局部变量仅限于局部范围，其含义相对简单容易理解，只需要简单注释即可。全局变量一般作用于多个文件，或者整个工程，因此，其含义相对更复杂，所以在注释的时候，最好描述清楚其具体含义，就是尽量全面描述。# Q; O2 W _0 [+ B
（提示：全局变量尽量少用）5、拼音注释 1.总述可能一个变量、一个函数包含的意思非常复杂，需要多个单词拼写而成，此时对拼写内容就需要详细注释。2.说明注释的通常写法是包含正确大小写和结尾句号的完整叙述性语句. 大多数情况下, 完整的句子比句子片段可读性更高. 短一点的注释, 比如代码行尾注释, 可以随意点, 但依然要注意风格的一致性。同时，注释中的拼写、逗号也很重要。虽然被别人指出该用分号时却用了逗号多少有些尴尬, 但清晰易读的代码还是很重要的. 正确的标点, 拼写和语法对此会有很大帮助6、TODO注释 1.总述对那些临时的, 短期的解决方案, 或已经够好但仍不完美的代码使用 TODO 注释。TODO 注释要使用全大写的字符串 TODO, 在随后的圆括号里写上你的名字, 邮件地址, bug ID, 或其它身份标识和与这一 TODO 相关的 issue. 主要目的是让添加注释的人 (也是可以请求提供更多细节的人) 可根据规范的 TODO 格式进行查找. 添加 TODO 注释并不意味着你要自己来修正, 因此当你加上带有姓名的 TODO 时, 一般都是写上自己的名字。声明：本文素材来源于牛逼的工程师网友！/ c; P* A3 V8 q# y4 V
-END-/ q L$ o$ G s3 p0 [
往期推荐：点击图片即可跳转阅读
. L, Y$ F/ Z6 \7 V9 ~$ l: ^2 y
) o2 b; q$ W( G& V9 R & g7 ?7 X D1 E+ ~+ _. k
% @2 z5 I I7 K1 y+ ?0 o4 f
, g4 u8 f7 B" h7 q3 o6 v. a: r. T
55ggcmb3edx64067201609.jpg
+ j0 i/ Z: X _9 S" Q & {$ C- q$ ~: I
2025年，抽屉里的嵌入式开发板，早就已经写满了岁月的痕迹！
' j4 N4 d7 o, w1 B1 _ ; o6 O5 G9 q+ j8 F# E" ]
) B& s( B+ \5 d/ V. k
7 h) n$ e# \ `& ?6 m! `0 p
' q+ v( z( O5 x+ a Z5 r5 H r/ K5 ^9 C
mvuuxh3wqua64067201709.jpg
1 F/ i" M1 I* k- Z+ B
7 @- m0 `' w4 R9 w" W9 X4 N" r
一些不太成熟的嵌入式系统设计观念！
! C0 o7 X- n) g% N) U% Q
; z, `+ P! m: Z3 j s
; [; i' B7 o# B5 m; q+ L+ p # r( l8 N/ B* s2 [2 L# n. p' n
1ur1chwemjo64067201809.jpg
7 ]0 ~. J: E; m' {6 Y8 n
- ?7 y& N# d6 |' ~7 I
嵌入式软件出现内存泄漏的时候，如何进行排查和分析？
: R5 r4 ^) H: f: t5 I% c
# q0 P! K& S8 j+ ~% E
8 e0 A4 K5 v" ~' e0 X $ o5 W/ R! \/ d. H, X
我是老温，一名热爱学习的嵌入式工程师& v' R g2 q, s1 @5 e4 m
关注我，一起变得更加优秀！; m1 b( h1 B, D5 d8 I/ L
r55hzw1yrhe64067201910.png
|
|
电子产业一站式赋能平台
窥视卡
置顶卡
变色卡
