How to Properly Document Your Python Code
The skills I demoed here can be learned through taking Data Science with Machine Learning bootcamp with NYC Data Science Academy.
Recently, you learned about the best practices that you can follow on naming conventions for better readability of your Python code. In this article, you will learn how you can create clearer and more concise documentation of your code and understand the importance of this process for better collaboration.
Documentation is one of the simplest and most important ways to strengthen your code and make it more readable. This process is important for colleagues and clients, but it also greatly impacts your comprehension of the code you write after not seeing it for weeks or months. This critical habit is something we share with our students through our bootcamps and courses.
Documentation Basics
You can think of documentation as a mini instructional manual written alongside your code, consisting of lines that can be seen but not executed. This means that a user can read your documentation, but it won’t impact how your program runs. It is an easy and essential way to make your code more interpretable, andan effective method to help collaborators understand the form and function of your code.
When documenting your code, you should explain what the code does and how to use it, not how it works. This practice will keep your documentation clear and concise.
Commenting
Code commenting is a great habit when you want to explain your thought process or what a specific piece of code is doing. A comment is a remark you write within your script (generally a single line, but it can be more if necessary) to further clarify the code that immediately follows. To add a comment, you simply write a sentence with a hash mark (#) preceding it. Python will know that this line is a comment, and although it will appear for the reader to see, it will not be executed.
You should comment minute details that aren’t obvious or areas you want to highlight. However, be careful not to go overboard with your commenting. The goal is simple documentation; over-commenting your script can clutter the syntax and have the opposite effect.
Docstring
Docstring is a long string used to describe what a function, method, or class does. Unlike a comment, that is an isolated remark, docstring describes a chunk of code’s overall use and function. Docstring is included at the beginning of a function, method, or class definition and is created by wrapping text with three quotation marks. This syntax operates in the same way as a comment, where the code will be visible but not executed when running your program.
The docstring should not describe how a function or class works, but rather what it does and how to use it. The long string should be the first lines beneath the class, method, or function definition.
Something we have adopted and recommended is adding a short arrow after argument descriptions to identify the expected types of input arguments and returned values. This is shown in the example above where name: Name of the pet dog when he adds -> and names it str. This indicates that the object is expected to be of string type. Additionally, we do this to show that the age attribute is expected to be an integer.
This brief overview is just to get you started, and we go into much more detail about documentation in this workshop. Understanding how to better explain your code will impress your coworkers and employers by saving you the time and headaches involved when deciphering another person’s code.
Ready to advance your programming skills? Check out this three-course program focused on building and advancing your Python Programming skills, or start your journey towards data science mastery by enrolling in our upcoming remote live and online bootcamps this Winter!
About Authors
Zoe Zbar
View all posts by Zoe Zbar >