google code style

注釋

文檔字符串是包, 模塊, 類或函數里的第一個語句. 這些字符串可以通過對象的doc成員被自動提取, 并且被pydoc所用. (你可以在你的模塊上運行pydoc試一把, 看看它長什么樣). 我們對文檔字符串的慣例是使用三重雙引號""" ( PEP-257 ).

一個文檔字符串應該這樣組織: 首先是一行以句號, 問號或驚嘆號結尾的概述(或者該文檔字符串單純只有一行). 接著是一個空行.接著是文檔字符串剩下的部分, 它應該與文檔字符串的第一行的第一個引號對齊.

模塊注釋

每個文件應該包含一個許可樣板. 根據項目使用的許可(例如, Apache 2.0, BSD, LGPL, GPL), 選擇合適的樣板。如下圖中井號開頭的部分:

模塊注釋.PNG
模塊注釋-多行.png

函數注釋

這里說的函數包括函數, 方法, 以及生成器。函數必須要有文檔字符串, 除非它滿足以下條件:

  • 外部不可見
  • 非常短小
  • 簡單明了

目的:文檔字符串應該提供足夠的信息, 當別人編寫代碼調用該函數時, 他不需要看一行代碼, 只要看文檔字符串就可以了.
要寫: 函數做什么, 以及輸入和輸出的詳細描述.
不要寫: 描述”怎么做”, 除非是一些復雜的算法.
其他: 復雜的代碼, 在代碼旁邊加注釋會比使用文檔字符串更有意義.

函數的幾個方面應該在特定的小節中進行描述記錄, 每節應該以一個標題行開始. 標題行以冒號結尾. 除標題行外, 節的其他內容應被縮進2個空格.

Args:

列出每個參數的名字, 并在名字后使用一個冒號和一個空格, 分隔對該參數的描述. 如果描述太長超過了單行80字符,使用2或者4個空格的懸掛縮進(與文件其他部分保持一致). 描述應該包括所需的類型和含義. 如果一個函數接受*foo(可變長度參數列表)或者**bar (任意關鍵字參數), 應該詳細列出*foo和**bar.

Returns: (或者 Yields: 用于生成器)
描述返回值的類型和語義. 如果函數返回None, 這一部分可以省略.

Raises:
列出與接口有關的所有異常.

英文注釋
函數注釋以動詞開頭,單數第三人稱,首字母大寫
好的函數,只用一個動詞

char1(str): The first Chinese character to be compared.
函數注釋.png

類注釋

描述該類, 如果你的類有公共屬性(Attributes), 那么文檔中應該有一個屬性(Attributes)段. 并且應該遵守和函數參數相同的格式.

類注釋.png

塊注釋行注釋

最需要寫注釋的是代碼中那些技巧性的部分. 如果你在下次 代碼審查 的時候必須解釋一下, 那么你應該現在就給它寫注釋.

對于復雜的操作, 應該在其操作開始前寫上若干行注釋. 對于不是一目了然的代碼, 應在其行尾添加注釋.

塊注釋和行注釋.png

導入

導入總應該放在文件頂部, 位于模塊注釋和文檔字符串之后, 模塊全局變量和常量之前.

每個導入應該獨占一行.

Yes: import os
     import sys
No:  import os, sys

導入應該按照從最通用到最不通用的順序分組:

  • 標準庫導入
  • 第三方庫導入
  • 應用程序指定導入
包導入-按常用程度分組-按字母順序排列.png

每種分組中, 每部分之間空一行, 應該根據每個模塊的完整包路徑按字典序排序, 忽略大小寫.

import foo
from foo import bar
from foo.bar import baz
from foo.bar import Quux
from Foob import ar
最后編輯于
?著作權歸作者所有,轉載或內容合作請聯系作者
平臺聲明:文章內容(如有圖片或視頻亦包括在內)由作者上傳并發布,文章內容僅代表作者本人觀點,簡書系信息發布平臺,僅提供信息存儲服務。

推薦閱讀更多精彩內容

  • Python是一種對代碼風格很重視的語言,從縮進就能看出這一點,Python強調易于理解。最近在負責代碼重構的工作...
    知曰閱讀 11,074評論 1 85
  • Spring Cloud為開發人員提供了快速構建分布式系統中一些常見模式的工具(例如配置管理,服務發現,斷路器,智...
    卡卡羅2017閱讀 134,868評論 18 139
  • 〇、前言 本文共108張圖,流量黨請慎重! 歷時1個半月,我把自己學習Python基礎知識的框架詳細梳理了一遍。 ...
    Raxxie閱讀 19,025評論 17 410
  • 源地址:http://www.runoob.com/w3cnote/google-python-styleguid...
    skaiger閱讀 513評論 0 0
  • 參考 --Google Python Style Guide --Google Python 風格指南 - 中文版...
    LittleWizard閱讀 2,749評論 0 4