盡管在一個(gè)人的代碼中應(yīng)添加多少注釋之間存在意見(jiàn)分歧，但我認(rèn)為可以肯定地說(shuō)，大多數(shù)開(kāi)發(fā)人員都同意以下代碼段中的注釋是多余的：

// increment the total total++;

在該示例中，代碼很簡(jiǎn)單，并且實(shí)際上是不言自明的，用標(biāo)準(zhǔn)的Java運(yùn)算符遞增了一個(gè)得體的命名變量total 。 幸運(yùn)的是，我現(xiàn)在沒(méi)有像以前那樣看到明顯不必要的評(píng)論類(lèi)型。

我仍然在其中似乎比我更希望看到多余注釋的一個(gè)方面與導(dǎo)致解釋性日志語(yǔ)句的代碼情況相關(guān)。 尤其是當(dāng)導(dǎo)致log語(yǔ)句的情況有些棘手時(shí)，似乎有時(shí)會(huì)希望向?qū)?lái)將要閱讀和維護(hù)該代碼的開(kāi)發(fā)人員寫(xiě)評(píng)論，并希望記錄相關(guān)信息以供使用。在以后調(diào)試特殊條件。 在大多數(shù)情況下，精心設(shè)計(jì)的日志消息（如其他精心設(shè)計(jì)的可執(zhí)行代碼）可以說(shuō)明一切，而無(wú)需其他注釋。

盡管編寫(xiě)自我記錄的日志記錄代碼與編寫(xiě)自我記錄的任何可執(zhí)行代碼在很大程度上相似，但是日志記錄代碼具有能夠在日志消息中表達(dá)任意詳細(xì)信息的優(yōu)點(diǎn)。 普通代碼受編程語(yǔ)言支持的結(jié)構(gòu)的限制，并且有時(shí)語(yǔ)言的結(jié)構(gòu)可能不如人們希望的那樣表達(dá)意圖。 記錄的消息在可表達(dá)的內(nèi)容方面的限制要少得多。 不利的一面是，更改代碼后，記錄的消息通常更容易被忽略。 必須進(jìn)行代碼更改，但是日志消息通常可以保持不變（即使它們應(yīng)該已經(jīng)更改），并且直到將來(lái)某個(gè)時(shí)候記錄該語(yǔ)句時(shí)，才會(huì)注意到這種遺漏。 盡管如此，與注釋相比，已記錄的消息具有更好的機(jī)會(huì)來(lái)進(jìn)行更改/更新，注釋僅在代碼讀取期間才被公開(kāi)。

使用日志消息來(lái)表達(dá)特殊條件而不是代碼注釋的附帶好處是，這可以導(dǎo)致編寫(xiě)簡(jiǎn)潔而透徹的日志消息時(shí)要遵守更多的紀(jì)律。 通過(guò)記錄的消息而不是代碼內(nèi)注釋進(jìn)行“注釋”的另一個(gè)好處是，可以在情況發(fā)生時(shí)在運(yùn)行時(shí)編寫(xiě)消息，并提供對(duì)代碼行為的寶貴見(jiàn)解，而這些行為在分析靜態(tài)代碼時(shí)根本不可用。

以下是兩個(gè)代碼清單，一個(gè)使用代碼內(nèi)注釋，另一個(gè)使用日志記錄，以表達(dá)對(duì)將來(lái)維護(hù)此代碼的開(kāi)發(fā)人員相同的看法。 在這兩種情況下，都記錄了業(yè)務(wù)邏輯考慮因素，即2016年美國(guó)國(guó)家橄欖球聯(lián)盟 （NFL）超級(jí)碗（ 丹佛野馬隊(duì)獲勝）沒(méi)有使用傳統(tǒng)的羅馬數(shù)字命名約定來(lái)命名 。 它沒(méi)有像以前的超級(jí)碗那樣被冠以“ L”的稱(chēng)號(hào)，而是被冠以“ 50”的稱(chēng)號(hào)。 這是業(yè)務(wù)邏輯規(guī)則類(lèi)型的精心設(shè)計(jì)的示例，通常以代碼注釋形式表示。 第10行是此處列出的每個(gè)代碼的重點(diǎn)。

private int convertToSuperBowlYear(final String superBowlNumber) {int superBowlYear;if (superBowlNumber == null || superBowlNumber.isEmpty()){superBowlYear = 0;}else if (superBowlNumber.equals("L")){// Super Bowl 50 was not named with the conventional Roman Numeral, so using '50' instead of 'L'superBowlYear = 2016;}else{superBowlYear = getSuperBowlYearFromNumber(getDecimalNumber(superBowlNumber));}return superBowlYear; }private int convertToSuperBowlYear(final String superBowlNumber) {int superBowlYear;if (superBowlNumber == null || superBowlNumber.isEmpty()){superBowlYear = 0;}else if (superBowlNumber.equals("L")){logger.fine("Super Bowl 50 was not named with the conventional Roman Numeral, so using '50' instead of 'L'.");superBowlYear = 2016;}else{superBowlYear = getSuperBowlYearFromNumber(getDecimalNumber(superBowlNumber));}return superBowlYear; }

這里未顯示方法getSuperBowlYearFromNumber(int)和getDecimalNumber(String)實(shí)現(xiàn)，因?yàn)樗鼈儗?duì)本次討論不重要。 這里重要的是，“ L”不是有效的超級(jí)碗編號(hào)，因此在確定超級(jí)碗的年份時(shí)必須使用“ 50”而不是“ L”。 如果開(kāi)發(fā)人員不熟悉NFL或它的超級(jí)碗命名約定，并且不熟悉2016年超級(jí)碗的命名約定，則需要某種類(lèi)型的注釋，以了解為什么一個(gè)超級(jí)碗與其他超級(jí)碗?yún)^(qū)別對(duì)待。

作為旁注并談到羅馬數(shù)字，令人驚訝的是，網(wǎng)絡(luò)上有多少Java代碼示例可在羅馬數(shù)字和基于十進(jìn)制的整數(shù)之間進(jìn)行轉(zhuǎn)換。 其中包括： 將羅馬數(shù)字轉(zhuǎn)換為十進(jìn)制 ， 將羅馬數(shù)字轉(zhuǎn)換為介于1到3999之間的 十進(jìn)制，使用Java 將羅馬數(shù)字轉(zhuǎn)換為十進(jìn)制，在Java中將羅馬數(shù)字轉(zhuǎn)換為十進(jìn)制以及如何將羅馬數(shù)字轉(zhuǎn)換為整數(shù) 。 我懷疑有很多家庭作業(yè)問(wèn)題會(huì) 激發(fā)大量的代碼示例。

Alexey最近發(fā)布了博客文章“ 用警告日志消息替換代碼中的TODO注釋？ 他指出，在他以前曾寫(xiě)過(guò)“ TODO”注釋的情況下，他已經(jīng)開(kāi)始寫(xiě)警告和錯(cuò)誤級(jí)別的日志消息。 這是使用日志消息代替注釋的更具體，更明顯的示例。 就阿列克謝而言，他之所以這樣做，是因?yàn)樗庾R(shí)到自己“總是忘記”“待辦事項(xiàng)”，而且“很少被發(fā)現(xiàn)，而且?guī)缀跤肋h(yuǎn)無(wú)法解決”。 Alexey的結(jié)論是：“這就是為什么我建議您嘗試通過(guò)在日志中寫(xiě)下您的評(píng)論，您的想法甚至是您的疑問(wèn)來(lái)嘗試這種方法：這將幫助您，甚至可以使您和您的同事開(kāi)心！”

在某些情況下，可能添加到源注釋中的內(nèi)容可能不適合添加到日志消息中。 這樣的情況包括評(píng)論的冗長(zhǎng)或評(píng)論的敏感性。 還值得注意的是，某些注釋級(jí)別的日志消息可能永遠(yuǎn)不會(huì)被記錄，因?yàn)樗鼈兊娜罩炯?jí)別設(shè)置得如此具體，以致在代碼執(zhí)行過(guò)程中永遠(yuǎn)不會(huì)真正啟用日志級(jí)別。 但是，在許多情況下，使用簡(jiǎn)潔而透徹的日志消息而不是代碼內(nèi)注釋來(lái)與將來(lái)的開(kāi)發(fā)人員和您將來(lái)的自己進(jìn)行通信具有優(yōu)勢(shì)。

翻譯自: https://www.javacodegeeks.com/2017/12/log-message-executable-code-comment.html

總結(jié)

以上是生活随笔為你收集整理的日志消息是可执行代码和注释的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。