研发之路： C代码注释引发的“血案”

野性酷女 2022-04-18 02:20 168阅读 0赞

出处：[研发之路： C代码注释引发的“血案”][C]

没有血案，但有些冲突。不是代码bug，我要讲注释风格。

这位看官，既然来了，且读且评吧。故事是真实的，如有雷同纯属巧合。

事情是这样的，有人离职，公司调我补缺。那个系统一直有个工程师在维护，参与该系统的新人来了又走，他始终泰若磐石。刚过去一个礼拜，我就心下窃吼：“坑爹啊!”，也彻底体会到什么叫---绝对的权威、专家。该软件系统，是公司发家的支柱产品，涉及十几个国家x七八个机型，700+个文件(C语言，所有.c .h档)，十几万行代码，尽两百个跨模块全局变量，编译条件成百上千......(好吧，这是找借口、吐槽的节奏)

尽管有名义上的交接，和几次和声细语的密切指导。但真正独立展开工作时，许多小功能增删改，我都要折腾个好几天才能厘清代码调用关系、算法原理，然后找到修改点谨慎细微龟速前行。进度追踪的人有的时候也催毛了，直接请专家大师出手，咔咔咔，不到半天就搞定了。当然，前期我当然尽量的”不耻上问”，但人吗，总是有遇到被激发“骨气”的时候。

这几天，好不容易搞好一个全新的功能模块，把代码推送给他合并编译。不曾想，出现了让我泣血的一幕。

我眼睁睁地、眼睁睁看着她把我辛苦敲入的代码*注释*/\*\*/通通换成//，一份精美的代码，顿时成渣。

我询问缘由，她的回答是: 当代码里面充满*注释*符号/\*\*/时，她想要用/\*\*/注释整段代码时，就会很麻烦。 我理解了，因为/\*\*/不支持嵌套。比如下面这样的语句是编译不过的。

/\*

a = b+c; /\* 注释 \*/

\*/

我的手抬了抬，终究作罢。虽然我感觉到尊严被践踏，心爱的作品被蹂躏，但我还是开始反思。

许多软件规范、专家、有经验的工程，都建议或要求注释代码最好使用 /\*\*/，他们的理由大略如下:

1. “//” 的注释的严密性不够。 例如

// 注释语句 ??/

a = b+c;

此时，a = b+c在一些*编译器*不会被执行。

因为'??/'会被*编译器*当作 \\，变成C语言的换行符。于是这段代码等同于

// 注释语句 a = b+c ;

就会被注释掉。大家有兴趣的，不妨去搜索一下'C语言 三字母词'

当然，哪怕没有??/， 自己打盹碰到delete键也是会屏蔽掉a=b+c的

2. “//” 的注释，是C++发展后才引进的。 有些早期的C*编译器*对这种注释是不支持的。代码要做到全平台兼容，这点是必需要考虑的。

因此，老外定义的C语言软件规范，无论是MISRA还是CMMI，一般都要求所有代码注释必须使用/\*\*/。

**　　君不见，那uCOS的最新版本源码，所有注释都是/\*\*/。**

**　　君不见，那STM32的最新固件库，洋洋洒洒几十个文件，通篇皆没有用到//。**

正是基于这样的理由，让我的心中充满了愠怒。但我仍然没有当场反驳她，因为这些理由还有些苍白无力。

1. 当时，那个什么三字母词“??x”到底是什么我已经忘了，没法立刻做试验编译给她看。

而且时候我里面作了编译实验，得到的是

'filename.c', line xxxx: Warning: \#2532-D: support for trigraphs is disabled xx代码语句xx // ??/

trigraph金山词霸---> \[traigra:f\]三字母词

看吧，编译器都警告了，默认是不支持的。

2. 而且，所谓的//是C++的，早期的c编译器不支持。

这点谁鸟啊，我们只要现在，只用最新版本的编译器。

**　　所以，我还要继续思考。**

**　　我要维护这个传统，为自己代言......**

**我开始思考，还有什么强劲有力的理由，来支持我恪守的真理：c语言代码*注释*必须使用/\*\*/.**

**　　有的!**

倘若所有代码里面的*注释*用到/\*\*/时，当你要*注释*掉这段代码时，如果不想忍受*编译器*的嵌套报警，又懒得把一个个/\*\*/换成//的话。那么你还有如下选择。

1) 慎重思考下是否删光这段代码，如果还有些不舍，那就先'备份'(git推送)一下再删光。因此，

**理由一：使用/\*\*/注释代码，会使软件系统减少冗余的僵尸代码，鼓励程序员的程序备份行为。**

2) 或者用编译条件圈起来，如下。

\#if (XXX\_ENABLE)

func(a, b, c); /\* 注释 \*/

...... /\* 注释 \*/

\#endif

那么你不得不考虑xxx的命名，如何更加一目了然，再写点注释什么的，表明对这段代码“弃而不舍”的缘由。因此，

**　　理由二：使用/\*\*/注释代码，会鼓励程序员删除代码时，三思而后行，并且注明舍弃的理由。**

3) 当然，偷懒的人还是会用 \#if 0 \#endif圈起来， 如下，

\#if 0

func(a, b, c); /\* 注释 \*/

...... /\* 注释 \*/

\#endif

而且不会写任何注释表明删除的理由。然而，“\#if 0”是一个如此的醒目，很容易成为一个评估软件质量、工作绩效的搜索关键词。从管理的角度，这个是可以量化的。因此，

**　　理由三: 使用/\*\*/注释代码，有利于公司进行软件质量控管，对程序员绩效考核。**

这三个理由，足够为自己代言吗?

**延伸阅读：**

[C语言实现FFT(快速傅里叶变换)][C_FFT]  
[C语言的那些小秘密之动态数组][C 1]  
[C语言的那些小秘密之异常处理][C 2]  
[硬件工程师的10个C语言技巧][10_C]  
[C语言难点及分析][C 3]  
[如何写出高效优美的单片机C语言代码？][C 4]

回复：运算放大器、傅里叶、阻抗、小波、type c、信号、单片机、示波器、模拟、毕设、电阻、DSP、电路、面试、电源、FPGA、USB、CAN（回复你想看的）

[C]: https://www.cc362.com/content/o1E77nZop3.html
[C_FFT]: http://mp.weixin.qq.com/s?__biz=MjM5MzUxMTAwMg==&mid=206317766&idx=5&sn=d66ede8e2df9a5afb5c454cab118b165&scene=21#wechat_redirect
[C 1]: http://mp.weixin.qq.com/s?__biz=MjM5MzUxMTAwMg==&mid=207070420&idx=4&sn=f0dec1abe2917a847c34d233c9c78cbc&scene=21#wechat_redirect
[C 2]: http://mp.weixin.qq.com/s?__biz=MjM5MzUxMTAwMg==&mid=209554221&idx=4&sn=07e8f1c873f5efc5019980c4e088beea&scene=21#wechat_redirect
[10_C]: http://mp.weixin.qq.com/s?__biz=MjM5MzUxMTAwMg==&mid=200792329&idx=2&sn=e34608c1fa563da7cd990ad268e99477&scene=21#wechat_redirect
[C 3]: http://mp.weixin.qq.com/s?__biz=MjM5MzUxMTAwMg==&mid=205471540&idx=1&sn=869d639c30df4a1258604c1896dc9a4f&scene=21#wechat_redirect
[C 4]: http://mp.weixin.qq.com/s?__biz=MjM5MzUxMTAwMg==&mid=205027846&idx=2&sn=1c8060517c25c16dce2d5ea55c670ca8&scene=21#wechat_redirect