編寫代碼注釋的最佳實(shí)踐

時(shí)間：2021-11-08 15:55:15

關(guān)鍵字：代碼編寫

手機(jī)看文章

掃描二維碼
隨時(shí)隨地手機(jī)看文章

[導(dǎo)讀]關(guān)注、星標(biāo)公眾號，直達(dá)精彩內(nèi)容來源：CSDN（ID：CSDNnews）作者：EllenSpertus|?譯者：王雪迎??雖然有很多資源可以幫助程序員編寫更好的代碼，比如書籍或靜態(tài)分析器，但是很少有資源可被用于編寫更好的注釋。雖然度量一個(gè)程序中的注釋數(shù)量很容易，但衡量注釋的質(zhì)量卻很...

雖然有很多資源可以幫助程序員編寫更好的代碼，比如書籍或靜態(tài)分析器，但是很少有資源可被用于編寫更好的注釋。雖然度量一個(gè)程序中的注釋數(shù)量很容易，但衡量注釋的質(zhì)量卻很難，而且兩者并不一定相關(guān)。差的注釋比根本不寫注釋更糟糕。這里有一些規(guī)則可以幫助你實(shí)現(xiàn)一種折中的方法。

麻省理工學(xué)院的著名教授Hal Abelson曾說過：“程序必須寫給人們閱讀，而只是附帶地讓機(jī)器執(zhí)行?！彪m然他可能故意低估了運(yùn)行代碼的重要性，但卻注意到了程序有兩種截然不同的受眾。編譯器和解釋器會忽略注釋，找出同等容易理解的所有語法正確的程序。而人類讀者則完全不同。我們發(fā)現(xiàn)有些程序比其它的更難理解，此時(shí)就會通過查看注釋來幫助我們理解這些程序。

雖然有很多資源可以幫助程序員編寫更好的代碼，比如書籍或靜態(tài)分析器，但是很少有資源可被用于編寫更好的注釋。雖然度量一個(gè)程序中的注釋數(shù)量很容易，但衡量注釋的質(zhì)量卻很難，而且兩者并不一定相關(guān)。差的注釋比根本不寫注釋更糟糕。正如Peter Vogel所述：

編寫并維護(hù)注釋是一項(xiàng)開銷。
編譯器不會檢查注釋，因此無法確定注釋是否正確。
另一方面，你可以保證計(jì)算機(jī)完全按照你的代碼所示運(yùn)行。

所有這些觀點(diǎn)都是正確的，但如果走到另一個(gè)極端，即從不寫注釋，那將是一個(gè)錯(cuò)誤。這里有一些規(guī)則可以幫助你實(shí)現(xiàn)一種折中的方法：

規(guī)則1：注釋不應(yīng)與代碼重復(fù)。
規(guī)則2：好的注釋不能成為代碼不清晰的借口。
規(guī)則3：如果無法寫出一個(gè)清晰的注釋，代碼可能有問題。
規(guī)則4：注釋應(yīng)該消除混亂，而不是引起混亂。
規(guī)則5：在注釋中解釋不規(guī)范的代碼。
規(guī)則6：提供復(fù)制代碼的原始出處鏈接。
規(guī)則7：在可能提供幫助的地方引入指向外部參考的鏈接。
規(guī)則8：在修復(fù)bug時(shí)添加注釋。
規(guī)則9：使用注釋來標(biāo)記未完成的實(shí)現(xiàn)。

本文其余部分將逐條解釋這些規(guī)則，提供示例并說明如何以及何時(shí)應(yīng)用它們。

規(guī)則1：注釋不應(yīng)與代碼重復(fù)

許多初級程序員會寫太多注釋，因?yàn)樗麄兘邮芰巳腴T指導(dǎo)老師的培訓(xùn)。我曾見過計(jì)算機(jī)科學(xué)系的高年級學(xué)生為每對大括號加上一條注釋，以表示該塊結(jié)束：

if (x > 3) { …} // if 我也聽說過老師要求學(xué)生對每一行代碼進(jìn)行注釋。雖然這對極為初級者來說可能是一個(gè)合理的策略，但這樣的注釋就像是訓(xùn)練輪，在大孩子騎車時(shí)應(yīng)該去掉。

不添加任何信息的注釋具有負(fù)價(jià)值，因?yàn)樗鼈儯?/span>

增加視覺混亂
讀寫花時(shí)間
可能會過時(shí)

一個(gè)典型的壞示例為：

i = i 1; // Add one to i 它不添加任何信息，并切產(chǎn)生維護(hù)成本。

每一行代碼都需要注釋的策略在Reddit上都受到了相當(dāng)?shù)某靶Γ?/span>

// create a for loop // <-- commentfor // start for loop( // round bracket // newlineint // type for declarationi // name for declaration= // assignment operator for declaration0 // start value for i

規(guī)則2：好的注釋不能成為代碼不清晰的借口

注釋的另一個(gè)誤用是提供本應(yīng)包含在代碼中的信息。一個(gè)簡單的例子是，有人用一個(gè)字母命名一個(gè)變量，然后添加一個(gè)描述其用途的注釋：

private static Node getBestChildNode(Node node) { Node n; // best child node candidate for (Node node: node.getChildren()) { // update n if the current state is better if (n == null || utility(node) > utility(n)) { n = node; } } return n;} 通過更好的變量命名，可以不需要再做注釋：

private static Node getBestChildNode(Node node) { Node bestNode; for (Node currentNode: node.getChildren()) { if (bestNode == null || utility(currentNode) > utility(bestNode)) { bestNode = currentNode; } } return bestNode;} 正如Kernighan和Plauger在編程風(fēng)格要素一書中所寫，“不要注釋糟糕的代碼 — 重寫它?！?/span>

規(guī)則3：如果無法寫出一個(gè)清晰的注釋，代碼可能有問題

Unix源代碼中最臭名昭著的注釋是“你不希望理解它”，它出現(xiàn)在一些恐怖的上下文切換代碼之前。Dennis Ritchie后來解釋說這是故意為之：“本意是想表達(dá)‘這不會出現(xiàn)在考試中’，而不是作為一種厚顏無恥的挑戰(zhàn)。”不幸的是，結(jié)果發(fā)現(xiàn)他與合作者Ken Thompson自己也理解不了，后來不得不重寫。

這讓人想起了Kernighan定律：

調(diào)試在一開始就比編寫程序困難一倍。因此，按照定義，如果你的代碼寫得非常巧妙，那么你就沒有足夠的能力來調(diào)試它。

警告讀者遠(yuǎn)離你的代碼就像打開汽車的危險(xiǎn)警示燈：承認(rèn)你正在做知法犯法的事情。相反，把代碼重寫成你充分理解的東西，或者更進(jìn)一步，直截了當(dāng)?shù)剡M(jìn)行解釋。

規(guī)則4：注釋應(yīng)該消除混亂，而不是引起混亂

如果沒有Steven Levy的黑客：計(jì)算機(jī)革命的英雄中的這個(gè)故事，任何關(guān)于負(fù)面注釋的討論都是不完整的：

[Peter Samson]拒絕在源代碼中添加注釋來解釋他在特定時(shí)間所做的事情，使其特別晦澀難懂。在一個(gè)分發(fā)良好的程序中，Samson繼續(xù)編寫了數(shù)百條匯編語言指令，其中只有一條包含1750數(shù)字的指令帶有注釋。注釋是RIPJSB，人們絞盡腦汁研究它的含義，直到有人發(fā)現(xiàn)1750年是巴赫去世的那一年，而Samson寫的注釋是Rest In Peace Johann Sebastian Bach（安息吧，約翰·塞巴斯蒂安·巴赫）的縮寫。

雖然我和別人一樣欣賞一個(gè)好的黑客，但這種注釋不可效仿。如果你的注釋引起混亂而不是消除混亂，刪除它。

規(guī)則5：在注釋中解釋不規(guī)范的代碼

注釋掉其他人可能認(rèn)為不需要或冗余的代碼是個(gè)好主意，比如來自App Inventor的代碼（我所有的正面示例均源于此）：

final Object value = (new JSONTokener(jsonString)).nextValue();// Note that JSONTokener.nextValue() may return// a value equals() to null.if (value == null || value.equals(null)) { return null;} 如果沒有注釋，有人可能會“簡化”代碼或?qū)⑵湟暈橐粋€(gè)神秘但必不可少的咒語。寫下為什么需要這些代碼，可以節(jié)省未來讀者的時(shí)間并解除他們的焦慮。

需要對是否注釋代碼做出判斷。在學(xué)習(xí)Kotlin時(shí)，我遇到了Android教程中的代碼：

if (b == true) 我立即想到是否可以用以下代碼取代：

if (b) 就像在Java中一樣。經(jīng)過一點(diǎn)研究，我了解到可以為null的布爾變量會顯式地與true進(jìn)行比較，以避免出現(xiàn)難看的null檢查：

if (b != null

本站聲明：本文章由作者或相關(guān)機(jī)構(gòu)授權(quán)發(fā)布，目的在于傳遞更多信息，并不代表本站贊同其觀點(diǎn)，本站亦不保證或承諾內(nèi)容真實(shí)性等。需要轉(zhuǎn)載請聯(lián)系該專欄作者，如若文章內(nèi)容侵犯您的權(quán)益，請及時(shí)聯(lián)系本站刪除。

換一批

阿維塔、賽力斯已入股！華為引望可能成“中國博世”

9月2日消息，不造車的華為或?qū)⒋呱龈蟮莫?dú)角獸公司，隨著阿維塔和賽力斯的入局，華為引望愈發(fā)顯得引人矚目。

關(guān)鍵字：阿維塔塞力斯華為

[美通社全球TMT]

Trianz與AWS達(dá)成戰(zhàn)略合作協(xié)議，徹底改變云采用和管理方式

加利福尼亞州圣克拉拉縣2024年8月30日 /美通社/ -- 數(shù)字化轉(zhuǎn)型技術(shù)解決方案公司Trianz今天宣布，該公司與Amazon Web Services （AWS）簽訂了...

關(guān)鍵字： AWS AN BSP 數(shù)字化

[美通社全球TMT]

人工智能驅(qū)動(dòng)工具SODA V將顛覆汽車市場，使汽車開發(fā)時(shí)間和成本降低90%

倫敦2024年8月29日 /美通社/ -- 英國汽車技術(shù)公司SODA.Auto推出其旗艦產(chǎn)品SODA V，這是全球首款涵蓋汽車工程師從創(chuàng)意到認(rèn)證的所有需求的工具，可用于創(chuàng)建軟件定義汽車。 SODA V工具的開發(fā)耗時(shí)1.5...

關(guān)鍵字：汽車人工智能智能驅(qū)動(dòng) BSP

[美通社全球TMT]

從容應(yīng)對未知風(fēng)險(xiǎn)----解密亞馬遜云科技的韌性之道

北京2024年8月28日 /美通社/ -- 越來越多用戶希望企業(yè)業(yè)務(wù)能7×24不間斷運(yùn)行，同時(shí)企業(yè)卻面臨越來越多業(yè)務(wù)中斷的風(fēng)險(xiǎn)，如企業(yè)系統(tǒng)復(fù)雜性的增加，頻繁的功能更新和發(fā)布等。如何確保業(yè)務(wù)連續(xù)性，提升韌性，成...

關(guān)鍵字：亞馬遜解密控制平面 BSP

[通信先鋒]

中國游戲市場開始復(fù)蘇！騰訊、網(wǎng)易等巨頭縮減在日本投資

8月30日消息，據(jù)媒體報(bào)道，騰訊和網(wǎng)易近期正在縮減他們對日本游戲市場的投資。

關(guān)鍵字：騰訊編碼器 CPU

[通信先鋒]

獨(dú)立自主！華為董事：致力打造不依賴西方的技術(shù)

8月28日消息，今天上午，2024中國國際大數(shù)據(jù)產(chǎn)業(yè)博覽會開幕式在貴陽舉行，華為董事、質(zhì)量流程IT總裁陶景文發(fā)表了演講。

關(guān)鍵字：華為 12nm EDA 半導(dǎo)體

[通信先鋒]

華為張平安：數(shù)字世界話語權(quán)最終由生態(tài)繁榮決定！

8月28日消息，在2024中國國際大數(shù)據(jù)產(chǎn)業(yè)博覽會上，華為常務(wù)董事、華為云CEO張平安發(fā)表演講稱，數(shù)字世界的話語權(quán)最終是由生態(tài)的繁榮決定的。

關(guān)鍵字：華為 12nm 手機(jī) 衛(wèi)星通信

[美通社全球TMT]

中國通信服務(wù)公布2024年中期業(yè)績

要點(diǎn)：有效應(yīng)對環(huán)境變化，經(jīng)營業(yè)績穩(wěn)中有升落實(shí)提質(zhì)增效舉措，毛利潤率延續(xù)升勢戰(zhàn)略布局成效顯著，戰(zhàn)新業(yè)務(wù)引領(lǐng)增長以科技創(chuàng)新為引領(lǐng)，提升企業(yè)核心競爭力堅(jiān)持高質(zhì)量發(fā)展策略，塑強(qiáng)核心競爭優(yōu)勢...

關(guān)鍵字：通信 BSP 電信運(yùn)營商數(shù)字經(jīng)濟(jì)

[美通社全球TMT]

NVI技術(shù)創(chuàng)新聯(lián)盟成立！自主生態(tài)將帶動(dòng)產(chǎn)業(yè)鏈高速發(fā)展

北京2024年8月27日 /美通社/ -- 8月21日，由中央廣播電視總臺與中國電影電視技術(shù)學(xué)會聯(lián)合牽頭組建的NVI技術(shù)創(chuàng)新聯(lián)盟在BIRTV2024超高清全產(chǎn)業(yè)鏈發(fā)展研討會上宣布正式成立。活動(dòng)現(xiàn)場 NVI技術(shù)創(chuàng)新聯(lián)...

關(guān)鍵字： VI 傳輸協(xié)議音頻 BSP

[美通社全球TMT]