Do you want to write cleaner, more maintainable Python code? Join us as we delve into the art and science of commenting in Python. Whether you’re a beginner or a seasoned coder, understanding the value and techniques of commenting will help you improve the readability of your code. So, let’s get started!
You’ll learn not only “what is” Python code commenting, but also why it’s an essential coding practice you should adopt.
Table of contents
What Are Python Code Comments?
Python code comments are lines in your code that Python interpreter ignores. These non-executable lines are intended to provide important instructions, explanations or context to developers who might use or maintain the code in future. Code comments come in two flavors: single-line comments and multi-line comments.
The main purpose of code commenting is to create clearer, more understandable code. Comments are like notes to other developers (or your future self) about how a piece of code works, why a certain solution was chosen, or what a specific function does.
Mastering the art of commenting can make you a more effective programmer. It makes your code more maintainable and readable, saves much debugging time, and makes collaboration with other programmers smoother.
Writing Single-line Comments in Python
Single-line comments in Python are denoted with a hashtag (#) at the start of the line. The Python interpreter will ignore anything on a line after a hashtag.
# This is a single line comment
print('Hello, World!') # This comment is ignored by PythonIn the above example, ‘Hello, World!’ is printed to the console. Python ignores the first line (a single-line comment) and the comment after the print statement is also ignored.
Writing Multi-line Comments in Python
For longer comments that span multiple lines, Python uses triple quotes. They can either be three single quotes (”’) or three double quotes (“””). Anything between triple quotes that isn’t part of a string is ignored by Python and serves as a comment.
'''
This is a multi-line
Python comment.
Python interpreter will
simply ignore these lines
'''
print('Hello, World!')The first four lines in the example above is a multi-line comment. Python ignores it, and the interpretation starts directly from the print statement.
Documenting Functions with Comments
We can also use comments to explain what our custom functions do. This is a core aspect of the Python’s Docstring format. The Docstring of a function is written in triple quotes and is usually located directly under the function definition.
def add_numbers(a, b): ''' This function takes two arguments, and returns their sum. ''' return a + b
In the previous example, the multi-line comment explains what the function ‘add_numbers’ does.
Writing TODO Comments
Finally, you can use comments to leave “TODO” notes for yourself and other developers. These notes are commonly used to highlight areas of the code that need work.
# TODO: Refactor this function for better performance def my_func(a, b): return a + b
In the above example, we indicate that the function ‘my_func’ needs to be refactored.
Using Commenting for Code Debugging
Another important use of comments in Python is for debugging code. When trying to track down the root cause of a bug, it can be helpful to “comment out”, or turn certain lines of code into comments to isolate the issue.
'''
# Below code needs debugging
'''
'''
print('This is before the erroneous code')
# erroneous_code_here
print('This is after the erroneous code')
'''In the example above, the code ‘erroneous_code_here’ is commented out for debugging purposes.
Ignoring Multiple Lines of Code
If you want to ignore multiple lines of code, enclose them within triple quotes.
'''
print('This code will be ignored')
my_var = 5 + 10
print(my_var)
'''
print('This code will run')In this example, the first block of code enclosed in triple quotes is ignored. The ‘print(‘This code will run’)’ statement is executed, as it’s not part of the multi-line comment.
Injecting Metadata Using Comments
Comments can also be used to inject metadata into your Python file or script. For example, ‘magic comments’ can be used to specify the encoding of a Python source file or the interpreter path for Unix/Linux systems.
# -*- coding: utf-8 -*- # This magic comment specifies the file encoding
#!/usr/bin/env python3 # This magic comment specifies the path of interpreter
The first example demonstrates a magic comment that specifies the file encoding. The second example sets the interpreter path, a common practice in Unix/Linux systems.
Inline Comments
Inline comments are placed on the same line as a statement, following the code itself. While they can be useful, they should be used sparingly as they can make code harder to read if overused.
my_var = 15 # Initializing my variable
The inline comment ‘Initializing my variable‘ is added to provide context for the variable declaration code.
Becoming a Python Pro – The Journey Continues
Understanding the art of effective commenting undoubtedly improves your Python coding skills. But why stop there? Your journey to become a Python pro is only just beginning. There’s so much more to explore!
The Python Mini-Degree is a comprehensive collection of Python programming courses carefully curated by the Zenva team. This extensive course bundle encompasses a wide range of topics – coding basics, object-oriented programming, algorithm development, game creation, and even building your own apps with popular Python libraries and frameworks like Pygame, Tkinter, and Kivy.
Whatever your level of programming experience, the Python Mini-Degree is the perfect learning pathway. You can learn at your own pace, enjoy support from expert mentors, and gain practical experience by completing step-by-step projects. This degree can be a game-changer, opening doors to countless opportunities in various industries, particularly if you are interested in data science.
Looking for more specific Python tutorials? We also have an extensive collection of Python courses on various specialized topics. Each course is crafted with the same dedication and commitment to help you advance your coding expertise.
Coding is a journey, and with Zenva, that journey can take you from beginner to professional. So, let’s continue learning!
Conclusion
Mastering Python commenting techniques is just a small step in your coding journey, but a significant one. It lays the foundation for writing clear, maintainable, and collaborative Python code. Whether you’re just starting or striving to be the best, the art of commenting is a tool that will always serve you well. Advanced or beginner, you can always improve your Python skills.
Let’s map out the rest of your learning journey together. Consider joining our Python Mini-Degree today and leap forward towards your goal of becoming a Python professional. Here at Zenva, we can’t wait to see how far you’ll go!
Did you come across any errors in this tutorial? Please let us know by completing this form and we’ll look into it!
FINAL DAYS: Unlock coding courses in Unity, Godot, Unreal, Python and more.
