Python程式碼註釋的一些基礎知識
在編寫Python程式碼時，確保您的程式碼易於被其他人理解是很重要的。給變數、函式起合適的名字以及合理地組織程式碼都是很好的方法。
使用註釋是增加程式碼可讀性的另一個方便簡單且重要的方法！
我們將介紹編寫Python註釋的一些基礎知識。您將學習如何優雅地編寫乾淨、簡潔的註釋，以及瞭解何時您可能根本不需要編寫任何註釋。
為什麼註釋程式碼如此重要
註釋是任何程式的一個組成部分，它們可以以註釋塊的形式或者在程式碼行中出現，來幫助闡明解釋一個複雜的函式。
在深入研究不同型別的註釋之前，讓我們仔細看看為什麼程式碼註釋如此重要。
假設在以下兩種情況中，程式設計師不對程式碼進行註釋。
當閱讀你自己的程式碼時
客戶端A希望在最後一刻部署他們的Web服務，截止日期就快到了，所以你決定先把它整體先做好，所有“額外”的東西如文件、適當的註釋等等之後再新增。
最終，在最後期限時，及時地部署了Web服務。
但當你還沒來及進行添加註釋時，你就迎來了老闆要求馬上開始的新專案，在進行新專案的同時，你可能會把客戶A的程式碼註釋忘得一乾二淨。
六個月後，客戶A需要為相同的服務構建一個補丁來滿足一些新的需求。維護它是你的工作，因為你是第一個建造它的人。開啟文字編輯器後……
“我之前到底寫了什麼？！”
你花了幾個小時分析你的舊程式碼，但你完全迷失在混亂中。您當時非常匆忙，沒有正確命名變數，甚至沒有在適當的控制流中設定函式。最糟糕的是，指令碼中沒有任何註釋來告訴您什麼是什麼！
開發人員總是忘記他們自己的程式碼所做的事情，尤其是如果程式碼是在很久以前編寫的，或者是在很大的壓力下編寫的。當最後期限快到了，在電腦前幾個小時導致眼睛充血時，這種壓力可以用比平時更混亂的程式碼形式反映出來。
一旦提交了專案，許多開發人員就會因太累了，根本無法回過頭來註釋他們的程式碼。當到了之後重新來用它的時候，可能要花上幾個小時來分析自己所寫的東西。
邊寫程式碼邊寫註釋是防止上述情況發生的一個很好的方法，請善待未來的你！
當別人在閱讀你的程式碼時
假設你是從事一個小型Django專案的唯一開發人員，感覺自己很好地理解了自己的程式碼，所以你不傾向於花費更多的時間來編寫註釋或任何其他說明文件。
可能到年底，你的“小Django專案”已經變成了一個“20000行程式碼”的專案，而您的主管正在安排更多的開發人員來幫助維護它。
新的開發人員努力工作，以迅速投入進來，但在合作的頭幾天，你便會意識到他們會遇到一些麻煩。在專案程式碼中，你使用了一些奇怪的變數名，並使用超級簡潔的語法編寫。這就導致新員工會花費大量的時間逐行遍歷您的程式碼，以試圖弄清楚它是如何工作的。
在這種情況下，在程式碼中使用註釋可以很好地幫助其他開發人員讀懂你的程式碼，你可以通過從專案一開始就對程式碼進行註釋來幫助與其他開發人員的合作。
如何用Python編寫註釋
現在我們已經知道了為什麼程式碼註釋如此重要，那麼讓我們來看一些有關注釋的基本知識，以便熟悉如何正確地使用它。
Python註釋基礎
要用Python編寫註釋，只需將“#”放在您的註釋內容之前：
Python會忽略在#標記之後到行尾的所有內容，您可以在程式碼中的任何位置插入它們，甚至可以在程式碼行中使用：
當你執行上述程式碼時，你只會看到This will run的輸出，其他的都會被忽略。
評論應該簡短、貼切、切中要害。PEP 8建議將程式碼保持在79個字元或更少，程式碼行中的註釋最多為72個字元。如果您的註釋接近或超過了該長度，則需要將其轉變為多行註釋。
Python多行註釋
不幸的是，Python無法像用C、Java和Go語言那樣編寫多行註釋：
在上述示例中，程式將忽略第一行，但其他行將引發語法錯誤。
相反，像Java這樣的語言可以很容易地將註釋擴充套件到多行：
程式會自動忽略/ 和 /之間的所有內容。
雖然Python沒有這種多行註釋功能，但可以在Python中建立多行註釋，主要有一下兩種簡單的方法。
第一種方法是在每一行後面簡單地按下回車鍵，新增一個新的#標記，然後繼續註釋：
程式將忽略以#標記開頭的每一行。
另一種方法是使用多行字串將註釋包裝在一組三引號中：
這與Java中的多行註釋類似，在Java中，包含在三元引號中的所有內容都將成為註釋。
雖然這貌似提供了多行註釋功能，但從技術上講，這並不是一個註釋。它僅僅是一個沒有分配給任何變數的字串，所以程式不會呼叫或引用它。不過，由於它在執行時會被忽略並且不會出現在位元組碼中，所以它可以有效地充當註釋。
但是，在放置這些多行“註釋”時要小心。根據它們在程式中的位置，它們有時可以轉換為docstring，這是與函式或方法相關聯的文件片段。如果您在函式定義之後將這些“註釋”放進去，那麼想要成為註釋的內容將與該物件相關聯。在使用這種多行註釋時要小心，如果有疑問，保險起見在後面的每一行上新增一個#標記即可。
Python註釋快捷鍵
每次需要添加註釋時，都要鍵入#標記可能會很繁瑣。那麼，我們能做些什麼來加快速度呢？這裡有一些技巧可以幫助你更快地添加註釋。
第一就是使用多個遊標，就是通過在螢幕上放置多個游標來完成任務。左鍵單擊時，只需按住ctrl或cmd鍵，就會看到螢幕上閃爍的線條：
當需要在多個地方對相同的事情進行註釋時，這是最有效的。
如果我們有很長一段文字需要註釋呢？或者批量將程式碼轉化為註釋，一行一行地註釋它可能需要很多時間！在這種情況下，只需選擇需要作為註釋的程式碼行並在PC上按Ctrl+/，或在Mac上按Cmd+/：
所有選中的程式碼前都將加上一個#標記，並被程式忽略。
如果註釋行數較多，或者正在閱讀的指令碼中的註釋非常長，那麼您的文字編輯器可能會讓您選擇使用左側的小箭頭摺疊它們：
只需單擊箭頭以隱藏註釋即可。如果長註釋分散在多行，或佔用程式大部分啟動時間的docstring中，這種方法效果最好。
將這些技巧結合在一起，將使您的程式碼註釋快速、簡單。
Python註釋最佳實踐
知道如何用Python編寫註釋相當重要，但同樣重要的是要確保註釋具有可讀性和易懂性。
以下技巧，可以幫助您編寫真正適合您的程式碼的註釋。
為自己編寫程式碼時
通過正確地註釋自己的程式碼，可以讓自己的程式設計師生活更輕鬆。即使沒有其他人會看到它，但你之後可能會反覆看它，這是你為它添加註釋的足夠的理由。畢竟，您是一個開發人員，應該讓您的程式碼容易理解。
為自己編寫註釋的一個非常有用的技巧是將其作為程式碼的大綱。如果不確定你的程式將如何發展，那麼您可以使用註釋來跟蹤剩餘的工作，甚至可以作為跟蹤高階程式流的一種方法。例如，使用註釋來勾勒虛擬碼中的函式：
這些註釋計劃出了get_top_cies，說明你準確地知道了你想要你的函式做什麼，後面可以很方便地將它翻譯成程式碼。
使用這樣的註釋可以幫助你保持頭腦清醒。當遍歷你的程式時，將知道要獲得一個功能齊全的指令碼，還需要做些什麼。在將註釋“轉換”成程式碼之後，請記住刪除任何已經變得多餘的註釋，這樣您的程式碼就可以保持清晰和乾淨。
還可以使用註釋作為除錯過程的一部分。註釋掉舊程式碼，看看它如何影響您的輸出。如果感覺輸出符合要求，那麼就可以去掉程式中註釋掉的程式碼，以提高程式碼的可讀性。您也可以使用程式版本控制，方便後面舊程式碼的找回。
最後，使用註釋來定義自己程式碼的棘手部分。如果你放下一個專案，幾個月或幾年後再回到它，你將需要花費大量的時間來重新熟悉你所寫的東西。為以防萬一你忘記自己的程式碼做了什麼，幫未來你一個忙，為其添加註釋，這樣以後就更容易更快速的重新讀懂它。
為他人編寫程式碼時
人們喜歡在閱讀文字資訊時跳來跳去，而閱讀程式碼也是如此。當代碼出了問題您必須弄清楚到底發生了什麼錯誤時，您才可能會逐行閱讀程式碼。
在大多數其他情況下，您將快速瀏覽變數和函式定義，以獲得要點。用簡單的註釋解釋正在發生的事情，能真正幫助開發人員瞭解在這個位置上做些什麼。
請善待你的同事，用註釋來幫助他們瀏覽你的程式碼。如果您有一個名稱不易理解的複雜方法或函式，您可能需要在def行後面新增一個簡短的註釋，以說明問題：
這可以幫助正在瀏覽你的程式碼的其他開發人員瞭解該函式的功能。
對於任何公共函式，我們都希望儘量包含一個關聯的docstring，不管它是否複雜：
此字串將成為函式的. doc 屬性，並將正式與該特定方法相關聯。
PEP 257指南有多行docstring的約定。這些文件字串出現在檔案的頂部，包括對整個指令碼以及它應該做什麼的高階概述：
像這樣的模組級文件字串將包含任何相關或需要知道的資訊，供開發人員閱讀。在編寫一個函式時，建議列出所有的類、異常和函式，以及每個類的一行摘要。
Python註釋最糟實踐
正如編寫Python註釋有好的標準一樣，有幾種型別的註釋要儘量避免。下面是一些例子。
避免：W.E.T.註釋
你的註釋應該是D.R.Y，這是“Don’t Repeat Yourself.”的縮寫，意味著你的程式碼註釋應該很少或沒有冗餘。您不需要對一段足以解釋自身的程式碼進行註釋，如下所示：
我們可以清楚地看到，a是返回值，因此沒有必要在註釋中特別地宣告這一點。這就是W.E.T.註釋，意思是“wrote everything twice”，也可以理解為“wasted everyone’s time”。
W.E.T.註釋可能是一個簡單的錯誤，特別是如果在編寫程式碼之前使用註釋來規劃程式碼。但是，一旦程式碼執行良好，一定要返回來刪除不必要的註釋。
避免：利用註釋來彌補程式碼
註釋有時會反映出您的程式碼可能存在深層次的問題，註釋是試圖隱藏程式碼自身問題的一種方法，但註釋應該支援你的程式碼，而不是試圖彌補它。如果您的程式碼編寫得很糟糕，那麼任何註釋都不會修復它。
讓我們以這個簡單的例子為例：
這段程式碼很不規範，在解釋程式碼的每一行之前都有一個註釋。通過為變數、函式和集合指定合理的名稱，這個指令碼可以變得更簡單，如下所示：
通過使用易於理解的命名方式，我們能夠刪除所有不必要的註釋，並減少程式碼的長度！
註釋一般要比它們支援的程式碼短很多，如果你花了太多時間解釋您所做的事情，那麼你需要返回並重構，以使你的程式碼更加清晰和簡潔。
避免：粗魯的註釋
這是在開發團隊工作時可能會出現的問題。當幾個人都在處理相同的程式碼時，其他人可能會檢查你所寫的內容並進行更改。有時，你可能會遇到一個敢於寫這樣的評論的人：
這種行為是極其不好的，如果不小心把這條註釋留在了那裡，然後一個客戶看到了它，這樣會很尷尬。你是一個專業人士，在你的註釋中加入粗俗的話會有辱自己的身份。
結語
學會優雅地使用註釋是很有價值的，您不僅學習瞭如何將其編寫得更清楚、更簡潔，而且無疑你也會對Python有更深入的瞭解。
知道如何用Python註釋可以使所有開發人員(包括您自己)的程式設計生活變得更輕鬆！它們可以幫助其他開發人員快速瞭解您的程式碼，並幫助您重新熟悉自己的舊程式碼。
注意，當使用註釋嘗試解釋或彌補編寫不良的程式碼時，返回並修改你的程式碼是更好的選擇。註釋以前編寫的程式碼，無論是你自己的程式碼還是其他開發人員的程式碼，都是練習用Python編寫註釋的好方法。
如果你對程式設計感興趣，想學習Python，小編整理了一些有深度的Python教程和參考資料，加入Python學習交流群【 784758214 】群內有安裝包和學習視訊資料，零基礎，進階，實戰免費的線上直播免費課程，希望可以幫助你快速瞭解Python。歡迎加入
