Python函数/方法docstring变量

Question

Let's say I what to write a docstring for the code bellow:

def some_thing_cool(age, name):
    better_age = age - 20
    cooler_name = name + 'awesome'
    bday_list = ['cake', 'balloons']
    return bday_list

Would it be like this:

def some_thing_cool(age, name):
    """Something for bday

    Args:
         age (int) : age of bday person
         name (string) : name of bday person
    Variable:
             better_age (int) : age - 20 for more pleasing age
             cooler_name (string) : name + awesome
             bday_list (list) : things to remember for bday
    Returns:
            bday_list (list) : best to return the list
    """
    better_age = age - 20
    cooler_name = name + 'awesome'
    bday_list = ['cake', 'balloons']
    return bday_list

Or should it be like this:

def some_thing_cool(age, name):
    """Something for bday

    Args:
         age (int) : age of bday person
         name (string) : name of bday person
    Returns:
            bday_list (list) : best to return the list
    """
    better_age = age - 20
    cooler_name = name + 'awesome'
    bday_list = ['cake', 'balloons']
    return bday_list

And most importantly why should it be one way or another? (Do not think about the docstring style, this is not of importance in this question.) Most example I could find online does not include any variables when displaying how to write good docstrings, and this is constantly on my mind.

Answer 1

I have flagged this is a primarily opinion based, but in general, docstrings should only show the inputs and outputs of functions, and include a human readable description of what the function does . Here's an example from the Python docstring documentation :

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero

Put yourself in the perspective of a reader who has never seen the code. If I am just looking to use your function, do I really care about every variable that's used within it? I really should only care about what it takes as input and what it provides as output.

Finally, please note that on Stack Overflow, questions should not be primarily opinion based as they tend to attract a lot of answers that aren't provably right or wrong. Check out How To Ask .

Answer 2

Those variables are not available outside of the function:

def some_thing_cool(age, name):
    better_age = age - 20 #this is a better age
    cooler_name = name + 'awesome' #This name is better (spaces not included)
    bday_list = ['cake', 'balloons']
    return bday_list

returnedValue = some_thing_cool(31.4159, 'Will')
#sets returned value equal to ['cake', 'balloons']

print(better_age) #NameError: name 'better_age' is not defined

Doc-strings are used to describe the function to people who want to use it. Since the variables are not available outside the function, no users of the function really care about them, and they just clutter up the docstring. You could add comments in the code to describe what the variables do so that anyone reading your code can understand it.

The reason that that the variables are unavailable is due to namespaces , you might want to look into them.

Answer 3

Well there is PEP-257 , but I personally don't think it's verbose enough

From the PEP:

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero
    ...

I personally use the following convention in my code

def get_versions(self, db_id):
    """ Simple call to look up all versions in a jira project
    :param db_id:   int: The ID of the Jira project
    :return:        list: of version objects
    :raises:        JIRAError on failure
    """
    ...

This is just pretty much what PyCharm does for you automatically though...