Python 中的註釋規範

在Python中，分爲單行註釋，多行註釋，特殊註釋

特殊註釋:

　　#!/usr/bin/env python

　　這樣的註釋意思是：Python告訴LINUX 去哪一個路徑下找Python的翻譯器

　　#-*-coding:utf-8-*-

　　這樣的註釋意思是:　告訴Python解釋器，如何解釋字符串中的編碼類型

多行註釋：/**/

　　通常用於給類文檔，函數文檔做註釋

單行註釋：#

 

 

註釋要求：

 

　　函數和方法註釋：

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

 

　　　　Returns: (或者 Yields: 用於生成器)描述返回值的類型和語義. 若是函數返回None, 這一部分能夠省略.

 

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

　　　　EXAMPLE:

　　　　　　

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None): """Fetches rows from a Bigtable.  Retrieves rows pertaining to the given keys from the Table instance  represented by big_table. Silly things may happen if  other_silly_variable is not None.  Args:  big_table: An open Bigtable Table instance.  keys: A sequence of strings representing the key of each table row  to fetch.  other_silly_variable: Another optional variable, that has a much  longer name than the other args, and which does nothing.  Returns:  A dict mapping keys to the corresponding table row data  fetched. Each row is represented as a tuple of strings. For  example:  {'Serak': ('Rigel VII', 'Preparer'),  'Zim': ('Irk', 'Invader'),  'Lrrr': ('Omicron Persei 8', 'Emperor')}  If a key from the keys argument is missing from the dictionary,  then that row was not found in the table.  Raises:  IOError: An error occurred accessing the bigtable.Table object.  """ pass

　　類的註釋

　　　　類應該在其定義下有一個用於描述該類的文檔字符串. 若是你的類有公共屬性(Attributes), 那麼文檔中應該有一個屬性(Attributes)段. 而且應該遵照和函數參數相同的格式.

　　　　

class SampleClass(object): """Summary of class here.  Longer class information....  Longer class information....  Attributes:  likes_spam: A boolean indicating if we like SPAM or not.  eggs: An integer count of the eggs we have laid.  """ def __init__(self, likes_spam=False): """Inits SampleClass with blah.""" self.likes_spam = likes_spam self.eggs = 0 def public_method(self): """Performs operation blah."""