How to Properly Document Your Python Code

Avatar
Posted on Sep 25, 2020

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 Author

Leave a Comment

No comments found.

View Posts by Categories


Our Recent Popular Posts


View Posts by Tags

#python #trainwithnycdsa 2019 airbnb Alex Baransky alumni Alumni Interview Alumni Reviews Alumni Spotlight alumni story Alumnus API Application artist aws beautiful soup Best Bootcamp Best Data Science 2019 Best Data Science Bootcamp Best Data Science Bootcamp 2020 Best Ranked Big Data Book Launch Book-Signing bootcamp Bootcamp Alumni Bootcamp Prep Bundles California Cancer Research capstone Career Career Day citibike clustering Coding Course Demo Course Report D3.js data Data Analyst data science Data Science Academy Data Science Bootcamp Data science jobs Data Science Reviews Data Scientist Data Scientist Jobs data visualization Deep Learning Demo Day Discount dplyr employer networking feature engineering Finance Financial Data Science Flask gbm Get Hired ggplot2 googleVis Hadoop higgs boson Hiring hiring partner events Hiring Partners Industry Experts Instructor Blog Instructor Interview Job Job Placement Jobs Jon Krohn JP Morgan Chase Kaggle Kickstarter lasso regression Lead Data Scienctist Lead Data Scientist leaflet linear regression Logistic Regression machine learning Maps matplotlib Medical Research Meet the team meetup Networking neural network Neural networks New Courses nlp NYC NYC Data Science nyc data science academy NYC Open Data NYCDSA NYCDSA Alumni Online Online Bootcamp Online Training Open Data painter pandas Part-time Portfolio Development prediction Prework Programming PwC python python machine learning python scrapy python web scraping python webscraping Python Workshop R R language R Programming R Shiny r studio R Visualization R Workshop R-bloggers random forest Ranking recommendation recommendation system regression Remote remote data science bootcamp Scrapy scrapy visualization seaborn Selenium sentiment analysis Shiny Shiny Dashboard Spark Special Special Summer Sports statistics streaming Student Interview Student Showcase SVM Switchup Tableau team TensorFlow Testimonial tf-idf Top Data Science Bootcamp twitter visualization web scraping Weekend Course What to expect word cloud word2vec XGBoost yelp