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