注釋?zhuān)總€(gè)程序員都寫(xiě)，但不是每個(gè)人都寫(xiě)得好。
一定有人跟你說(shuō)息裸，“注釋是好的”和“你應(yīng)該注釋你的代碼”。 但并非所有注釋都適用這兩句話。事實(shí)上，并不是所有的注釋都是好的！ 有些注釋會(huì)使代碼變得更糟放坏，而不是更好。
在本文中淤年，我們將了解注釋背后的一般原則以及如何在 Python 中注釋代碼（盡管這些原則適用于任何編程語(yǔ)言）。
事不宜遲溉苛，讓我們開(kāi)始吧弄诲！
避免WET注釋
您可能聽(tīng)說(shuō)過(guò) Write Everything Twice 或 WET齐遵。 這是一個(gè)編碼概念梗摇，在概念上與另一個(gè)稱(chēng)為 DRY 或不要重復(fù)自己的原則相反。所有這一切在注釋的上下文中意味著一個(gè)好的注釋不應(yīng)該簡(jiǎn)單地重申代碼正在做什么断序。
例如违诗，考慮以下代碼：
import time
def time_stuff(fun):
start_time = time.time()
fun()
end_time = time.time()
return end_time - start_time
這個(gè)函數(shù)可以記錄其他函數(shù)執(zhí)行的時(shí)間景图，以秒為單位较雕。 非常簡(jiǎn)單。
設(shè)想你要求一個(gè)初學(xué)者給你的項(xiàng)目中添加一些注釋?zhuān)赡芴砑恿艘韵聝?nèi)容：
import time
def time_stuff(fun):
# Record the start time
start_time = time.time()
fun()
end_time = time.time()
return end_time - start_time
這是一個(gè)非常WET的注釋挚币。注釋并沒(méi)有添加任何有用的東西，真的只是重申了一些已經(jīng)很明顯的東西扣典。像這樣的注釋沒(méi)有任何益處妆毕。 在某些時(shí)候，函數(shù)會(huì)發(fā)生變化贮尖，注釋也會(huì)過(guò)時(shí)笛粘。
那么它不僅沒(méi)有帶來(lái)任何開(kāi)始的價(jià)值，而且如果有人更改函數(shù)并忘記更新公共部分的注釋?zhuān)ㄟ@種情況一直發(fā)生）薪前，它會(huì)降低代碼的可讀性。
避免在代碼會(huì)做的地方寫(xiě)注釋
你知道什么樣的代碼比注釋良好的代碼更好嗎关斜？那就是不需要注釋的代碼示括。 這就是開(kāi)發(fā)人員應(yīng)該努力的方向。你可能會(huì)問(wèn)“這有什么重要的”痢畜？ 畢竟垛膝，您只需添加一兩行注釋即可快速向讀者解釋所有內(nèi)容鳍侣，從而避免他思考代碼的功能所帶來(lái)的麻煩。
原因是代碼很少是一成不變的吼拥，很可能會(huì)隨著時(shí)間的推移而進(jìn)化倚聚。如果該代碼依賴(lài)于擁有最新的注釋以便讀者有機(jī)會(huì)了解函數(shù)中發(fā)生了什么，那么維護(hù)這些注釋就變得與維護(hù)代碼一樣重要和繁重凿可。更改代碼后很容易忘記更新注釋惑折。
那么我們?nèi)绾沃貥?gòu)我們的代碼，以至于我們（經(jīng)常）甚至不需要注釋它呢枯跑？
例如唬复，考慮以下代碼：
def calc(x):
return x * x * 3.14
那些還記得學(xué)校幾何課的人可能會(huì)認(rèn)出這里的公式是圓的面積。 所以函數(shù) calc 的目的是全肮，對(duì)于給定的半徑 r 敞咧，計(jì)算圓的面積。
這個(gè)函數(shù)在代碼可讀性方面一點(diǎn)都不好辜腺。大部分人的直覺(jué)可能是像這樣注釋代碼：
def calc(x):
# Calculate area of circle for radius x
return x * x * 3.14
那是……更好休建。 但是該代碼仍然可以改進(jìn)∑懒疲考慮一下我們是否重寫(xiě)代碼本身测砂，以便它可以作為文檔一樣的去使用。
畢竟百匆，我們可以給函數(shù)和變量命名砌些，所以我們不妨充分利用它并使它們有意義。 這樣做通常比寫(xiě)任何注釋都要好用得多加匈。
讓我們像這樣重寫(xiě)函數(shù)：
import math
def calc_area_of_circle(radius):
return radius * radius * math.pi
是不是好很多存璃！
避免描述HOW，更多地考慮WHY
還有一點(diǎn)雕拼，好的注釋不應(yīng)該描述代碼的工作原理纵东。 相反，它應(yīng)該關(guān)注代碼為什么做某事啥寇。
但是有人會(huì)問(wèn)偎球，注釋不是用來(lái)幫助解釋代碼內(nèi)部工作原理的嗎？ 讓我解釋辑甜。
解釋代碼如何工作的注釋有兩個(gè)問(wèn)題衰絮。
首先，解釋某段代碼如何工作的注釋注定會(huì)過(guò)時(shí)磷醋。 注釋引用的代碼塊越大猫牡，過(guò)時(shí)的速度就越快。一旦發(fā)生這種情況子檀，注釋就會(huì)變得非常有害镊掖。新來(lái)理解代碼的人（或者甚至在你自己有一段時(shí)間沒(méi)有看這段代碼之后）很容易因?yàn)樽⑨尪`導(dǎo)代碼在做什么乃戈。您可能會(huì)爭(zhēng)辯說(shuō)，一個(gè)好的開(kāi)發(fā)人員應(yīng)該仔細(xì)檢查注釋是否準(zhǔn)確地描述準(zhǔn)確——但反過(guò)來(lái)想想亩进，注釋是為我們寫(xiě)代碼服務(wù)的症虑，為什么還要費(fèi)心把注釋放在首位呢？
只是描述代碼功能的注釋的第二個(gè)問(wèn)題是归薛，它只是突出了代碼編寫(xiě)的不太好的一種掩飾谍憔。我們應(yīng)該努力重構(gòu)我們的代碼，使其可讀且盡可能不言自明主籍。的確有時(shí)候习贫，重構(gòu)代碼使其通過(guò)閱讀就可以清楚地知道它是如何工作的，非常困難千元。 但作為一般經(jīng)驗(yàn)苫昌，描述代碼如何工作的注釋是很糟糕的。
注釋代碼為什么做某事幸海，可以為讀者提供更多更宏觀的項(xiàng)目或功能背景祟身。當(dāng)修復(fù)bug或向代碼添加新功能時(shí)，這會(huì)非常有幫助物独，因?yàn)殚_(kāi)發(fā)人員將首先了解為什么這段代碼會(huì)出現(xiàn)在這里袜硫，以及它試圖解決什么問(wèn)題。
總結(jié)
在本文中挡篓，我們了解了在 Python 中編寫(xiě)好的注釋的一些規(guī)則婉陷。 這些規(guī)則足夠通用，可以擴(kuò)展到大多數(shù)編程語(yǔ)言中官研。通過(guò)遵循這些簡(jiǎn)單的規(guī)則秽澳，你的注釋將會(huì)更加清晰。 最終阀参，這將使你的代碼變得更好肝集。
