Docstrings-video transcript

 

Documenting your code is super important, especially if you're working in

a group and you need to communicate to others what your functions do and

what kind of information they expect and return. A lot of times the

greatest benefactor of your documentation is yourself. It's easy to

believe as we start a project that we're going to remember why we wrote

our code in a certain way and how to call functions and what information

they need and what information they return. But as our program gets more

complex and as time goes by, that isn't always the case. Many times a year

has gone by and I come back to a little bit of code that I wrote and I

have no idea how to use it. Good documentation is important, even if

you're just writing your code for yourself.

Docstrings are one way that we can document our code in Python. A

docstring is just a string that we put at various places in our code. It

could be at the top of the file or it could be directly after the name of

a function or a method or a class.

Now, before we get started. There are two things I want to mention. First,

I might talk about some concepts that you haven't learned yet. That's

okay. Just come back to this video when you need it. Second, we are all on

a journey of personal growth, myself included. So you will see some videos

that don't exactly match the conventions that I'm talking about here. But

I would like you to follow these conventions. And as I can, I'll go back

and fix those videos.

Docstrings are governed by a document called PEP-257. It's one of the two

style guides that you'll hear referred to all the time in Python. The

other one is PEP-8. PEP-257 is pretty short and it leaves a lot up to you.

It describes what a docstring is and how it should be written and gives

some examples in different contexts.

So let's jump in and fix this file. This file doesn't have any

documentation in at all. We have two functions here and these functions

are contained within a file that we call a module. So we should have three

docstrings, one for each function and one for the module itself. Let's

start with the module level docstring. I'm going to give myself some room

here.

... (truncated to save space in this message)