Comments are a piece of text in a computer program that provides more information on the source code written.
Like every other programming language, Python has three types of comments: single-line comments, multi-line comments, and documentation strings to comment out code blocks.
Introduction to Python Comments
The primary purposes of using comments in Python are:
- Comments are used to describe the code. Adding comments to the code makes it more human-readable and makes it easy to maintain the code.
- Testing the code
- Comments can be used as documentation, meaning they can be used to explain the code or Metadata of the project
- We can use comments to prevent the execution of specific code blocks.
For example, let’s say you have written complex business logic, formulas, algorithms, etc. Then we need to document it using the comments that explain what the code does, thus improving the readability of the code in Python.
Python interpreter ignores the comments while executing the code and only interprets the code.
Types of comments in Python
There are three kinds of comments we can use in Python.
- Single-line comments
- Multi-line comments
- Documentation strings, aka docstrings
Let us look into details on how to use these comments in Python code with examples.
Single-line comments start with a hash sign
# followed by a single space and a text string. The hash
# works with only a single line of code, and any code that comes after a hash
# will be ignored and not executed.
Single-line comments are mainly used to describe the line of code; it is placed either before the line of code or after the line of code.
Let’s take an example to demonstrate single-line comments in Python.
Example of Single-line comment in Python
# This is a single-line comment example print("Hello World")
If you place the comment in the same line as a statement, you will have an inline comment.
Like single-line comments, inline comments begin with a hash (#) sign and are followed by a space and the comment text. Any code that comes after a hash
# will be ignored and not executed.
Let’s take an example to demonstrate inline comments in Python.
a = 4 b = 5 sum = a + b # Calculate the sum of a and b print(sum) # Print the Sum of a and b print("Hello World") # This is an example of an inline comment
Usually, in other languages like Go, C, C#, Java, etc., we can write a multi-line comment, as shown below.
/* This is an example of multi-line comment in Go lang */
Like other programming languages Python, do not have Multi-line comments.
**Python may not have any built-in mechanism for commenting out multiple lines. However, there are different ways to achieve this in Python. **
Using Hash in each line (#)
We can use multiple hash
# to write multi-line comments in Python. Each line with a hash sign (#) is considered a single-line comment. Hence we can use hash in each line that we need to comment.
Multi-line comments Example
# This is how we can achieve # Multi-line comments in Python print("Hello World")
Documentation strings, also called docstrings, are the string literal denoted with triple quotes that occur as the first statement in a module, function, class, or method definition. Conventions for writing good documentation strings (a.k.a. "docstrings") are immortalized in PEP 257.
Note: We can also use triple """ quotations to create docstrings.
Let’s take an example to demonstrate single-line docstring.
def Add(a,b): '''Takes two numbers as input and returns the sum of 2 numbers''' return a+b
Inside the triple quotation marks is the docstring of the function Add(), which appears right after its definition.
The multi-line docstring can span across multiple lines of code, starts with triple quotes("""), and ends with triple quotes (""").
We can use multi-line docstring as multi-line comments in Python to comment out a block of code.
The following example shows you how to use multi-line docstrings. Make sure to indent the leading ''' appropriately to avoid an IndentationError
Multi-line docstring example
def Add(a, b): """Takes two numbers as input Adds a and b Returns the sum of a and b as output """ return a + b print(Add(5, 6))
Note: As long as the string is not assigned to any Python variable, Python will read the code but then ignore it, and you have made a multi-line comment.
Best Practices for writing code comments
- Do not duplicate the code while explaining the code in comment blocks.
- Write precise and meaningful comments. Do not provide a detailed explanation and clarification of the code.
- Do not comment out the actual code; if a piece of code is not in use, it is better to delete it rather than comment it out for future use.
- Add Metadata and document style commenting, which provides an overview of the code, class, methods, parameters, and the return type.
- Provide links to external references if you have referred the code from online sources.
- Add the comments while fixing the bugs
- Do not overdo it