Write Pythonic Code Like a Seasoned Developer Transcripts
Chapter: Style guidance from PEP 8
Lecture: Documentation strings
Login or
purchase this course
to watch this video and the rest of the course contents.
0:01
Next, let's look at what PEP 8 says about documentation and docstrings. Here we have our some_method, method that I wrote,
0:09
and I added three more parameters, if I come down here and I say some_method, see there is sort of note help in the IntelliSense,
0:17
and if I say "look it up", PyCharm does a little work to say what the type hints would be if it could look at the types
0:24
the way the function is written, but it doesn't tell me really what a1, a2 or a3 mean, or what the method itself does,
0:31
and obviously it's poorly named, so this doesn't help as well. So what we should do is give it some docstrings,
0:36
and docstrings are just a string by itself on the first line of the method,
0:41
or module, if you're documenting the module or class, if you're documenting the class. So we can just say triple quote
0:47
and then I hit Enter and PyCharm will actually look at the method and help us out, so it knows it returns a value
0:52
and it knows it has three parameters called a1, a2 and a3, so when I hit Enter, I get the sort of structured way of documenting my method
1:00
so we'll say something like "some_method returns a larger of one or two", which is not actually what it even returns,
1:07
it's just a silly method I threw in there to talk about spaces, let's say this is a meaningful thing,
1:12
and let's say this will be the first value will be first item to compare I will say a2 is the second item to compare and a3 is actually
1:21
whether or not it should be reversed which again, doesn't mean anything. We'll say 1 or 2. So if we write this we can come down here
1:28
now and I say some_method, and look at it I could hit F1 or if I was in REPL I can type "help some_method" and I would see this-
1:37
some method returns the larger of 1 or 2, a1, first item to compare, a2 second item to compare, a3 should reverse, 1 or 2.
1:44
All right, so that's helpful, this is the recommended way to write these docstrings, according to PEP 8,
1:51
let me fix this, put a little space here, we'll go back and look at the picture. So the recommendation from PEP 8 is
1:58
we should write docstrings for all public symbols, modules, functions, classes and methods, and they are not really necessary for non-public items,
2:07
that's an implementation detail and you can do whatever you want there.