Summary: In this tutorial, you will learn how to add comments to your code. And you’ll learn various types of Python comments, including block comments, inline comments, and documentation chains.
Introduction to Python comments
Sometimes, you want to document the code you write. For example, you might want to note why a code snippet works. To do this, you use the comments.
Typically, comments are used to explain formulas, algorithms, and complex business logic.
When you run a program, the Python interpreter ignores comments and only interprets the code.
Python provides three types of comments, including block comments, inline comments, and documentation chains.
Python
block comments
A block comment explains the code that follows it. Typically, a block comment is indented at the same level as the code block.
To create a block comment, start with a single hash sign (#) followed by a single space and a text string. For
example:# increase the price by 5% price = price * 1.05Code language: Python (python)
Python
online comments When you place a comment
on the same line as a statement, you will have
an inline comment. Similar to a block comment, an inline comment
begins with a single hash sign (#) and is followed by a space and a text string.
The following example illustrates an inline comment
:salary = salary * 1.02 # increase salary by 2%Code language: Python (python)
Python document strings
A documentation string is a string
literal that is placed as the first few lines in a block of code, for example
, a function.
Unlike a regular comment, a documentation string can be accessed at run time using obj.__doc__ attribute where obj is the name of the function.
Typically, you use a documentation string to automatically generate code documentation.
Documentation strings are called docstrings.
Technically speaking, docstrings are not comments. They create anonymous variables that reference strings. Also, they are not ignored by the Python interpreter.
Python provides two types of docstrings: one-line docstrings and multi-line docstrings.
1) One-line docstrings
As the name implies, a
one-line docstring snaps
to a line. A one-line docstring begins with triple quotation marks (“””) and also ends with triple quotation marks (“””). In addition, there will be no blank lines before or after the one-line docstring string.
The following example illustrates a one-line docstring in
the quicksort():d ef quicksort() function: “”” sort the list using the quicksort “”” algorithm … Code language: Python (python)
2) Multiline document strings
Unlike a document string
, a multiline document string can span multiple lines. A multiline docstring also begins
with triple quotes (“””) and ends with triple quotation marks (“””).
The following example shows how to use multiline docstrings
:d ef increase(salary, percentage, rating): “”” increase salary base in grade and grade 1 – 2 no increase rating 3 – 4 increase 5% rating 4 – 6 increase 10% “””Code language: Python (python)Python multiline comments
Python does not support multiline comments.
However, you can use multiline docstrings as multiline comments. Guido van Rossum, the creator of Python, also recommended this.
It is good practice to keep your comment clear, concise, and explanatory. The ultimate goal is to save time and energy for you and other developers who will work on the code later on.
Summary
Use
- comments to document code when needed
- A block comment and an inline comment begin with a hash sign (#).
- Use docstrings for functions, modules, and classes.
.
