2011/07/22

python tips: googley style docstring

I surveyed some comment style in python. One is sphinx style and the other is google style (they are introduced in this site). However sphinx style is suitable for documentation using sphinx, its code legibility is poorer than google style. Below code is commented in google style.

#!/usr/bin/env python                                                           
#                                                                               
# Copyright 2011 Yuki OYABU Inc.                                                
#                                                                               
# Licensed under the Apache License, Version 2.0 (the "License");               
# you may not use this file except in compliance with the License.              
# You may obtain a copy of the License at                                       
#                                                                               
#     http://www.apache.org/licenses/LICENSE-2.0                                
#                                                                               
# Unless required by applicable law or agreed to in writing, software           
# distributed under the License is distributed on an "AS IS" BASIS,             
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.      
# See the License for the specific language governing permissions and           
# limitations under the License.                                                


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                        
    oahter_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 occured accessing the bigtable. Table object.              
    """
    pass


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."""

No comments:

Post a Comment

100