Python PEP8 編碼規範 注釋

標籤：oob   第一個   get   編碼規範   hit   com   相同   div   注釋   

　　與代碼相矛盾的注釋比沒有注釋還糟，當代碼更改時，優先更新對應的注釋！ 
　　注釋應該是完整的句子。如果一個注釋是一個短語或句子，它的第一個單詞應該大寫，除非它是以小寫字母開頭的標識符(永遠不要改變標識符的大小寫！)。 
　　如果注釋很短，結尾的句號可以省略。塊注釋一般由完整句子的一個或多個段落組成，並且每句話結束有個句號。 
　　在句尾結束的時候應該使用兩個空格。 
　　當用英文書寫時，遵循Strunk and White （譯註：《Strunk and White, The Elements of Style》）的書寫風格。 
　　在非英語國家的Python程式員，請使用英文寫注釋，除非你120%的確信你的代碼不會被使用其他語言的人閱讀。

塊注釋

　　塊注釋通常適用於跟隨它們的某些（或全部）代碼，並縮排到與代碼相同的層級。塊注釋的每一行開頭使用一個#和一個空格（除非塊注釋內部縮排文本）。 
　　塊注釋內部的段落通過只有一個#的空行分隔。、

行內注釋

　　有節制地使用行內注釋。 
　　行內注釋是與代碼語句同行的注釋。行內注釋和代碼至少要有兩個空格分隔。注釋由#和一個空格開始。 
　　事實上，如果狀態明顯的話，行內注釋是不必要的，反而會分散注意力。比如說下面這樣就不需要：

x = x + 1                 # Increment x

但有時，這樣做很有用：

x = x + 1                 # Compensate for border

文檔字串 

• 要為所有的公用模組，函數，類以及方法編寫文檔說明。非公用的方法沒有必要，但是應該有一個描述方法具體作用的注釋。這個注釋應該在def那一行之後。
• PEP 257 描述了寫出好的文檔說明相關的約定。特別需要注意的是，多行文檔說明使用的結尾三引號應該自成一行，例如：

"""Return a foobangOptional plotz says to frobnicate the bizbaz first."""

• 對於單行的文檔說明，尾部的三引號應該和文檔在同一行。

 

Python PEP8 編碼規範 注釋