0

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

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.

Improve this question
4
  • 2
    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. Commented Jul 24, 2018 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. Commented Jul 24, 2018 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. Commented Jul 24, 2018 at 23:06
  • 1
    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. Commented Jul 24, 2018 at 23:07

3 Answers 3

Reset to default
1

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.

Improve this answer
Sign up to request clarification or add additional context in comments.

1 Comment

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

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.

Improve this answer

Comments

0

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

Improve this answer

Comments

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.