|
我要無辜的坦白說，您遇到標題黨了。 沒有血案，但有些沖突。不是代碼bug，我要講注釋風格。 這位看官，既然來了，且讀且評吧。故事是真實的，如有雷同純屬巧合。 事情是這樣的，有人離職，公司調我補缺。那個系統一直有個工程師在維護，參與該系統的新人來了又走，他始終泰若磐石。剛過去一個禮拜，我就心下竊吼：“TMD坑爹啊!”，也徹底體會到什么叫---絕對的權威、專家。該軟件系統，是公司發家的支柱產品，涉及十幾個國家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”是一個如此的醒目，很容易成為一個評估軟件質量、工作績效的搜索關鍵詞。從管理的角度，這個是可以量化的。因此， 理由三: 使用/**/注釋代碼，有利于公司進行軟件質量控管，對程序員績效考核。 這三個理由，足夠為自己代言嗎? |
