How to Properly Document Your Python Code

and
Posted on Sep 25, 2020
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

Alex Baransky

Alex graduated from Columbia University with training in natural and technical sciences. He enjoys finding ways to utilize data science to answer questions efficiently and to improve the interpretability of results. Alex takes pride in his ability to...
View all posts by Alex Baransky >

Leave a Comment

No comments found.

View Posts by Categories


Our Recent Popular Posts


View Posts by Tags

#python #trainwithnycdsa 2019 2020 Revenue 3-points agriculture air quality airbnb airline alcohol Alex Baransky algorithm alumni Alumni Interview Alumni Reviews Alumni Spotlight alumni story Alumnus ames dataset ames housing dataset apartment rent API Application artist aws bank loans 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 boston safety Bundles cake recipe California Cancer Research capstone car price Career Career Day citibike classic cars classpass clustering Coding Course Demo Course Report covid 19 credit credit card crime frequency crops D3.js data data analysis Data Analyst data analytics data for tripadvisor reviews data science Data Science Academy Data Science Bootcamp Data science jobs Data Science Reviews Data Scientist Data Scientist Jobs data visualization database Deep Learning Demo Day Discount disney dplyr drug data e-commerce economy employee employee burnout employer networking environment feature engineering Finance Financial Data Science fitness studio Flask flight delay gbm Get Hired ggplot2 googleVis H20 Hadoop hallmark holiday movie happiness healthcare frauds higgs boson Hiring hiring partner events Hiring Partners hotels housing housing data housing predictions housing price hy-vee Income Industry Experts Injuries Instructor Blog Instructor Interview insurance italki Job Job Placement Jobs Jon Krohn JP Morgan Chase Kaggle Kickstarter las vegas airport lasso regression Lead Data Scienctist Lead Data Scientist leaflet league linear regression Logistic Regression machine learning Maps market matplotlib Medical Research Meet the team meetup methal health miami beach movie music Napoli NBA netflix Networking neural network Neural networks New Courses NHL nlp NYC NYC Data Science nyc data science academy NYC Open Data nyc property NYCDSA NYCDSA Alumni Online Online Bootcamp Online Training Open Data painter pandas Part-time performance phoenix pollutants Portfolio Development precision measurement prediction Prework Programming public safety PwC python Python Data Analysis python machine learning python scrapy python web scraping python webscraping Python Workshop R R Data Analysis 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 seafood type Selenium sentiment analysis sentiment classification Shiny Shiny Dashboard Spark Special Special Summer Sports statistics streaming Student Interview Student Showcase SVM Switchup Tableau teachers team team performance TensorFlow Testimonial tf-idf Top Data Science Bootcamp Top manufacturing companies Transfers tweets twitter videos visualization wallstreet wallstreetbets web scraping Weekend Course What to expect whiskey whiskeyadvocate wildfire word cloud word2vec XGBoost yelp youtube trending ZORI