Avoiding Common Docstring Mistakes

00:00 It’s time for you to take a stab at fixing these common docstring anti-patterns: unclear descriptions and parameters, not being clear about the behavior or characteristics of the function, class, or module.

00:11 Inconsistent formatting that could be mixing styles of docstring, using improper indentation levels, even misnaming headers, and missing return value explanations, which it’s pretty easy to forget to include, especially in a longer function.

00:26 Okay, go ahead and meet me in your IDE or text editor of choice. I’m here in VS Code, starting with the file vague_description.py. And you can find the starter code for each of these files in the course resources.

00:40 So let’s look at the function as is: def brew() with the parameter ingredients. Docstring: """Does something with the ingredients.""" Return the f-string, "Magical potion brewed" from ", " .join(ingredients). For a challenge, go ahead and pause the video here and write your own docstring based on this function.

00:59 You can use any style you want, but I’ll be showing you a multiline Google-style docstring. Okay, here’s what I would do first. Since it’s going to be multiline, the triple quotes will be on their own lines, and it needs a more descriptive summary.

01:14 Mixes the provided ingredients to brew a potion.

01:18 It’s Google-style, so it needs Args. Args: indent ingredients, which is a list of strings: Ingredients needed to brew the potion.

01:33 And it also needs Returns:, which is a string. The name of the completed potion. Alright, one down, two to go. Moving on to inconsistent_format.py, the function is def summon() with the parameters spell and caster, and the docstring: Summons a creature.

01:55 Parameters: spell dash: name of the spell as string. caster: string: name of the caster, Return the summoned creature (str).

02:05 So you can tell this looks like it should be Google-style, but the format is definitely way off. How would you fix it? The function isn’t implemented, but there should be enough information in the docstring for you to work with.

02:17 And if you like, you can think up your own implementation. Here’s my solution. Again, it’s multiline, so the quotes should be on their own line. Summons a creature is a little vague.

02:28 Change that to Summon the creature using the given spell. Add a space. "Parameters" should be Args: and there should be an indent before describing each arg. spell should include its type: spell (str): and a colon.

02:46 And then this should read: The name of the summoning spell. caster also needs a type, str,

03:00 and a description, The name of the person casting the spell.

03:04 Add a space before the next header, and again, “returns” should be Returns:

03:11 An indent followed by the type, str. And that should read: The name of the summoned creature.

03:22 Alright, one more. And that’s minimal_return_details .py. This function is def generate_shield() with a parameter strength.

03:33 Docstring: Generates a magical shield based on input strength. Args: strength: an integer strength level. Return: the f-string, "Shield with strength: {strength}". And yeah, it is easy to forget to add the return details, so go ahead and add them to the docstring.

03:50 Here’s how I would describe it.

03:53 Add a space. Returns: with an indent. Well, it’s a string, so str and definition:

04:03 A human-readable description of the generated shield.

04:07 So how’d you do if our docstrings were completely different? Don’t sweat it. As long as you follow the general guidelines and conventions, your docstrings will be fine.

04:16 The most important thing is to practice. It’s just like writing code. The more you do it, the better you’ll get. And all you have left now is to review what you’ve learned in the summary.

04:26 See you there.