Comments are like signposts which make a given code self-evident and highly readable. In Python, we can add single-line and multi-line Python comment. This tutorial will cover both these methods in detail. After reading this, you would know how to add a Python comment and which style to use.
Writing comments is a good programming practice. They are non-executable part of the code, yet quite essential in a program. These not only help other programmers working on the same project but the testers can also refer them for clarity on white-box testing.
It is best to add comments while you create or update a program otherwise you may lose the context. And comments written later may not be as effective as they should be.
Commenting is an art of expressing what a program is going to do at a very high-level. These are tagged lines of text to annotate a piece of code. In Python, we can apply two styles of comment: single-line and multiline.
Single-line Python comment
You might prefer to use a single line Python comment when there is need of short, quick comments for debugging. Single-line comments begin with a pound (#) symbol and automatically ends with an EOL (end of the line).
# Good code is self-documenting. print("Learn Python Step by Step!")
While putting a comment, make sure your comment is at the same indent level as the code beneath it. For example, you might annotate a function definition which doesn’t have any indentation. But the function could have blocks of code indented at multiple levels. So take care of the alignment, when you comment inside the internal code blocks.
# Define a list of months months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul','Aug','Sep','Oct','Nov','Dec'] # Function to print the calender months def showCalender(months): # For loop that traverses the list and prints the name of each month for month in months: print(month) showCalender(months)
Multiline Python comment
Python allows comments to span across multiple lines. Such comments are known as multiline or block comments. You can use this style of commenting to describe something more complicated.
This extended form of comments applies to some or all of the code that follows. Here is an example to use the multiline Python comment.
To add multiline comments, you should begin each line with the pound (#) symbol followed by a single space. You can divide a comment into paragraphs. Just add an empty line with a hash mark between each para.
Note: The symbol (#) is also known as the octothorpe. The term came from a group of engineers at Bell Labs while working on a first of the touch-tone keypads project.
# To Learn any language you must follow the below rules. # 1. Know the basic syntax, data types, control structures and conditional statements. # 2. Learn error handling and file I/O. # 3. Read about advanced data structures. # 4. Write functions and follow OOPs concepts. def main(): print("Let's start to learn Python.") ...
Python has the documentation strings (or docstrings) feature. It gives programmers an easy way of adding quick notes with every Python module, function, class, and method.
You can define a docstring by adding it as a string constant. It must be the first statement in the object’s (module, function, class, and method) definition.
The docstring has a much wider scope than a Python comment. Hence, it should describe what the function does, not how. Also, it is a good practice for all functions of a program to have a docstring.
You can define a docstring with the help of triple-quotation mark. Add one in the beginning and second at the end of the string. Just like multiline comments, docstring can also overlap to multiple lines.
Note: The strings defined using triple-quotation mark are docstring in Python. However, it might appear to you as a regular comment.
The strings beginning with triple quotes are still regular strings except the fact that they could spread to multiple lines. It means they are executable statements. And if they are not labeled, then they will be garbage collected as soon as the code executes.
The Python interpreter won’t ignore them as it does with the comments. However, if such a string is placed immediately after a function or class definition or on top of a module, then they turn into docstrings. You can access them using the following special variable.
def theFunction(): ''' This function demonstrate the use of docstring in Python. ''' print("Python docstrings are not comments.") print("nJust printing the docstring value...") print(theFunction.__doc__)
Wrap up – Python comment and docstring
Comments and docstrings add values to a program. They make your programs more readable and maintainable. Even if you need to refactor the same code later, then it would be easier to do with comments available.
Software spends only 10% time of its life in development and rest of 90% in maintenance.
Hence, always put relevant and useful comments or docstrings as they lead to more collaboration and speed up the code refactoring activities.