Python : Single Line Comment vs Multi Line Comment vs DocString
Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.
— John F. Woods
Hello World!!! In this blog post, we will go through single line comment, multi line comment & doc string in Python. Let’s get started.
What are comments in programming language?
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. Comments are lines that exist in computer programs that are ignored by compilers or interpreters. In simple words they are non-executable part of the code but very important in a program. We can place it anywhere in our code, on the same line or several lines.
Types of comments in Python:
- Single Line
- Multi Line**
Single Line Comments
We use the hash (#) symbol to start writing a comment.
Example : Single Line Comment
In the above example we can see a single line comment which is used to explain what we are gonna do in the trailing statement.
Example : Inline Comment
As seen in the above example comments can also be written in the same line.
Example : Using “#” in print() method
No need to confuse we can use “#” in print() method, here Python interpreter won’t ignore it.
Multi Line Comments
Comments that extend multiple lines are multi line comments. We can use this style of commenting to describe something more complicated.
Before moving on to the multi line comments in Python, first let’s understand how we write single and multi line comments in C?
In the below examples as we see that we use double slash // for single line comments and a multi line comments starts with a slash asterisk /* and finishes with an asterisk slash */ .
Example : Single Line Comment & Multi Line Comment in C
Code in C :
Output :
**In the above example we can observe that there is a dedicated syntax in C language to write the multi line comments. As such there is no concept of multi line comments in Python, but we can use hash (#) in the beginning of each line if the comments are long.
Note : Some says that ‘’’triple quotes’’’ can be used as multi line comments, which is wrong and I have explain this in the trailing sections.
Pros of using comments
Including comments in programs makes code more readable for humans as it provides some explanation about what each part of a program is doing. In general, it is a good idea to write comments while you are writing or updating a program as it is easy to forget your thought process later on, and comments written later may be less useful in the long term. These not only help other programmers working on the same project but the testers can also refer them for clarity on white-box testing.
DocString
Docstring is short for documentation string. It is not ignored by the Python interpreter. It gives programmers an easy way of adding quick notes with every Python method, class, module, package, etc which can be helpful .
We can define a docstring by adding it as a string constant, which is simply done with the help of triple-quotation mark. Add one in the beginning and second at the end of the string. Just like multi line comments, docstring can also extends to multiple lines.
Example : Doc String
Writing the doc string :
It must be the first statement in the object’s (method, class, module, package, etc) definition.
It should describe what the method/class/module/package does, not how.
Accessing the doc string :
The docstring can be accessed by the attribute __doc__ of the function, class, module, etc.
Pros of using docstring
As the name itself suggest it is used for documentation. It is used to describe what the object does. Also, it is a good practice for all functions of a program to have a docstring, as the function might be used by some other developers so it will help them in comprehending it easily.
Difference
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 assigned to a variable, 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. As we can see in the below example it’s been printed to the console. 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.
Example : Docstring not ignored by Python interpreter
Conclusion
So Python only has one way of doing comments and that is using #. Multi line comments with """triple quotes""" is a wrong way of doing it and one can say that multi line comment don’t actually exist in Python.
