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.

Talk Python's Mastodon Michael Kennedy's Mastodon