[Python] 注释规范

Posted on | Edited on | In

函数注释

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
def function(arg1, arg2...):
    """ [Brief description of function]
    
    [Detailed description of function]
    
    Args:
        [arg1]: [Description of arg1]
        [arg2]: [Description of arg2]
        ...
    
    Returns:
        [Description of returns]
        For example:
        
        [Example of returns]
        
        [Any supplementary description of returns]
    
    Raises:
        [exception_type]: [description of exception]
    
    """
    pass

以下为示例，摘自Rubick7的博客

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
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

类注释

1
2
3
4
5
6
7
8
9
10
11
class SampleClass(object):
    """[Summary of class]
    
    [More details about class]
    
    Attributes:
        [attr1]: [description of attr1]
        [attr2]: [description of attr2]
        ...
    
    """

以下为示例，摘自Rubick7的博客

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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."""