Python function/method docstring variables

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.

I can't imagine why you would document the internal variables of a function. What would be the point? They're internal, it is of nobody's business what they are called or what they do. — Daniel Roseman, Jul 24 '18 at 22:28
If you really need to specify the types of params and return values, don't use made-up ill-defined types like `string`, use the actual names you'd use in a type annotation, like `str`. And, ideally, `List[str]` instead of just `list`, because just knowing that it returns a list of _something_ isn't all that helpful. — abarnert, Jul 24 '18 at 23:04
More importantly, just repeating the name and type as the description isn't helpful at all. I already know that `age` is an age, `name` is a name, and `bday_list` is "to return the list"… Maybe tell me that `bday_list` is "decorations for birthday party" or something else I couldn't otherwise tell without reading the source code. — abarnert, Jul 24 '18 at 23:06
To add to what @DanielRoseman said: If you _do_ need to document what the internal variables do, you're documenting it for people reading the internal implementation, not for people reading the API spec (whether here or in a Sphinx-generated webpage). So, that should go as inline comments within the source code. — abarnert, Jul 24 '18 at 23:07

score 1 · Answer 1 · answered Jul 24 '18 at 22:32

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.

Was just posting a similar iteration of this, and agree about the opinion-based nature of the question. The documentation of the variables distracts from the purpose of the docstring which is to describe functionality, rather than internal state/values. — John Stark, Jul 24 '18 at 22:35

score 0 · Answer 2 · answered Jul 24 '18 at 22:35

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.

score 0 · Answer 3 · answered Jul 24 '18 at 22:36

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

Python function/method docstring variables

3 Answers3