1. Documentation
One of the big Software Engineering concepts that all python users benefit from is Documentation.
2. Documentation in Python
Documentation in python can take the form of comments. Comments in python are led by the pound symbol as you see here. They can sprinkle in information about your code for future collaborators.
Another way of documenting code is to use docstrings. Docstrings are invoked by the use of triple quotation marks like you see here. They are typically used to document functions, classes, and scripts for your users.
Let's look at both these in a little more detail.
3. Comments
Comments are used inline to document what a particular line of code is doing and why. They can appear on their own line or a the end of a line of code.
A big difference between docstrings and comments is that comments will not be seen by your users unless they are looking into your source code. The goal of comments is to make your code more readable for both yourself and collaborators.
4. Effective comments
There is some debate on the usefulness of comments.
Take a moment to look at these comments.
As you can see, they don't add much value; unless the code is trying to teach someone about Python basics, then these could be useful comments. So it's important to know your audience when commenting.
However, a good rule is that comments should explain why a line of code is doing something and not what the line of code is doing. Here is the same code with different comments to explain the why of the code.
In my opinion, over-commented code isn't nearly as big of a headache as under-commented code. If you ever question whether or not a comment is useful I would suggest adding the comment.
5. Docstrings
Comments are documentation for yourself and collaborators, docstrings are documentation for your users. Docstrings are what python outputs whenever a user calls help on your functions and classes.
Let's look at the anatomy of a docstring.
The first sections describe the functionality of what we're documenting.
6. Docstrings
Next, we document the parameters and return value of our function.
We use this particular syntax with the colons by convention so that downstream tools can take our docstrings and convert them into website based documentation. You can see an example of a webpage generated from a docstring formatted like ours at this link which show's the documentation for the popular Flask package.
7. Docstrings
Last, we can document example usage, and expected output.
The 3 chevrons show the example function call and the next line will represent the expected output.
8. Example docstring
Here we see a docstring actually filled out to describe a function and its usage.
It contains a brief description, information on the parameter & return values, and an example showing how the function is used.
In the case of this simple function, the optional details section wouldn't add much value so it's been omitted.
In addition to the docstring, we see comments explaining why the code was written a certain way, as opposed to what the code is doing.
9. Example docstring output
Now that we've written the docstring for the square function, users can access it by calling help. When they do they'll see this print out showing all the information they'd need to understand what it does and use it properly.
Note, as mentioned before, the user's don't see our comments that describe our implementation details to future colaborators.
10. Let's Practice
We just covered how to write effective comments and docstrings. Let's jump into some practice.