日本黄色一级经典视频|伊人久久精品视频|亚洲黄色色周成人视频九九九|av免费网址黄色小短片|黄色Av无码亚洲成年人|亚洲1区2区3区无码|真人黄片免费观看|无码一级小说欧美日免费三级|日韩中文字幕91在线看|精品久久久无码中文字幕边打电话

當(dāng)前位置：首頁(yè) > 嵌入式 > 技術(shù)讓夢(mèng)想更偉大

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

時(shí)間：2021-11-08 15:55:15
關(guān)鍵字： 代碼    編寫   
手機(jī)看文章

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

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




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


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


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


  1. 編寫并維護(hù)注釋是一項(xiàng)開銷。


  2. 編譯器不會(huì)檢查注釋，因此無(wú)法確定注釋是否正確。


  3. 另一方面，你可以保證計(jì)算機(jī)完全按照你的代碼所示運(yùn)行。


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


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


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


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


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


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


  • 規(guī)則6：提供復(fù)制代碼的原始出處鏈接。


  • 規(guī)則7：在可能提供幫助的地方引入指向外部參考的鏈接。


  • 規(guī)則8：在修復(fù)bug時(shí)添加注釋。


  • 規(guī)則9：使用注釋來(lái)標(biāo)記未完成的實(shí)現(xiàn)。


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



01


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



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


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


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


  • 增加視覺混亂


  • 讀寫花時(shí)間


  • 可能會(huì)過(guò)時(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


02


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



注釋的另一個(gè)誤用是提供本應(yīng)包含在代碼中的信息。一個(gè)簡(jiǎn)單的例子是，有人用一個(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;} 通過(guò)更好的變量命名，可以不需要再做注釋：


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)格要素一書中所寫，“不要注釋糟糕的代碼 — 重寫它。”



03


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



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


這讓人想起了Kernighan定律：


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


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



04


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



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


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


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



05


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



注釋掉其他人可能認(rèn)為不需要或冗余的代碼是個(gè)好主意，比如來(lái)自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;} 如果沒有注釋，有人可能會(huì)“簡(jiǎn)化”代碼或?qū)⑵湟暈橐粋€(gè)神秘但必不可少的咒語(yǔ)。寫下為什么需要這些代碼，可以節(jié)省未來(lái)讀者的時(shí)間并解除他們的焦慮。


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


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


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


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

LED驅(qū)動(dòng)電源的輸入包括高壓工頻交流(即市電)、低壓直流、高壓直流、低壓高頻交流(如電子變壓器的輸出)等。

關(guān)鍵字： 驅(qū)動(dòng)電源

在工業(yè)自動(dòng)化蓬勃發(fā)展的當(dāng)下，工業(yè)電機(jī)作為核心動(dòng)力設(shè)備，其驅(qū)動(dòng)電源的性能直接關(guān)系到整個(gè)系統(tǒng)的穩(wěn)定性和可靠性。其中，反電動(dòng)勢(shì)抑制與過(guò)流保護(hù)是驅(qū)動(dòng)電源設(shè)計(jì)中至關(guān)重要的兩個(gè)環(huán)節(jié)，集成化方案的設(shè)計(jì)成為提升電機(jī)驅(qū)動(dòng)性能的關(guān)鍵。

關(guān)鍵字： 工業(yè)電機(jī) 驅(qū)動(dòng)電源

LED 驅(qū)動(dòng)電源作為 LED 照明系統(tǒng)的 “心臟”，其穩(wěn)定性直接決定了整個(gè)照明設(shè)備的使用壽命。然而，在實(shí)際應(yīng)用中，LED 驅(qū)動(dòng)電源易損壞的問(wèn)題卻十分常見，不僅增加了維護(hù)成本，還影響了用戶體驗(yàn)。要解決這一問(wèn)題，需從設(shè)計(jì)、生...

關(guān)鍵字： 驅(qū)動(dòng)電源 照明系統(tǒng) 散熱

根據(jù)LED驅(qū)動(dòng)電源的公式，電感內(nèi)電流波動(dòng)大小和電感值成反比，輸出紋波和輸出電容值成反比。所以加大電感值和輸出電容值可以減小紋波。

關(guān)鍵字： LED 設(shè)計(jì) 驅(qū)動(dòng)電源

電動(dòng)汽車(EV)作為新能源汽車的重要代表，正逐漸成為全球汽車產(chǎn)業(yè)的重要發(fā)展方向。電動(dòng)汽車的核心技術(shù)之一是電機(jī)驅(qū)動(dòng)控制系統(tǒng)，而絕緣柵雙極型晶體管(IGBT)作為電機(jī)驅(qū)動(dòng)系統(tǒng)中的關(guān)鍵元件，其性能直接影響到電動(dòng)汽車的動(dòng)力性能和...

關(guān)鍵字： 電動(dòng)汽車 新能源 驅(qū)動(dòng)電源

在現(xiàn)代城市建設(shè)中，街道及停車場(chǎng)照明作為基礎(chǔ)設(shè)施的重要組成部分，其質(zhì)量和效率直接關(guān)系到城市的公共安全、居民生活質(zhì)量和能源利用效率。隨著科技的進(jìn)步，高亮度白光發(fā)光二極管(LED)因其獨(dú)特的優(yōu)勢(shì)逐漸取代傳統(tǒng)光源，成為大功率區(qū)域...

關(guān)鍵字： 發(fā)光二極管 驅(qū)動(dòng)電源 LED

LED通用照明設(shè)計(jì)工程師會(huì)遇到許多挑戰(zhàn)，如功率密度、功率因數(shù)校正(PFC)、空間受限和可靠性等。

關(guān)鍵字： LED 驅(qū)動(dòng)電源 功率因數(shù)校正

在LED照明技術(shù)日益普及的今天，LED驅(qū)動(dòng)電源的電磁干擾(EMI)問(wèn)題成為了一個(gè)不可忽視的挑戰(zhàn)。電磁干擾不僅會(huì)影響LED燈具的正常工作，還可能對(duì)周圍電子設(shè)備造成不利影響，甚至引發(fā)系統(tǒng)故障。因此，采取有效的硬件措施來(lái)解決L...

關(guān)鍵字： LED照明技術(shù) 電磁干擾 驅(qū)動(dòng)電源

開關(guān)電源具有效率高的特性,而且開關(guān)電源的變壓器體積比串聯(lián)穩(wěn)壓型電源的要小得多,電源電路比較整潔,整機(jī)重量也有所下降,所以,現(xiàn)在的LED驅(qū)動(dòng)電源

關(guān)鍵字： LED 驅(qū)動(dòng)電源 開關(guān)電源

LED驅(qū)動(dòng)電源是把電源供應(yīng)轉(zhuǎn)換為特定的電壓電流以驅(qū)動(dòng)LED發(fā)光的電壓轉(zhuǎn)換器，通常情況下：LED驅(qū)動(dòng)電源的輸入包括高壓工頻交流(即市電)、低壓直流、高壓直流、低壓高頻交流(如電子變壓器的輸出)等。

關(guān)鍵字： LED 隧道燈 驅(qū)動(dòng)電源
關(guān)閉