How to Write a Comment and Comment Out Lines in Python
In Python, use # to add descriptions as comments or to comment out unnecessary code.
Comments with #
Inline comments
Everything from # to the end of the line is ignored during execution. Code before # remains valid.
a = 1 # comment
If a comment contains another #, everything after the first # is considered part of the same comment.
a = 1 # comment # b = 2
A # inside a string is treated as a # character and not considered a comment.
s = 'abc # xyz'
Block comments
By placing a # at the beginning of a line, the entire line is considered a comment and ignored during execution.
# a = 1
Of course, if you place a # at the beginning of each line in a block, you can comment out multiple lines.
a = 1
# b = 2
# c = 3
# d = 4
e = 5
Recommended rules in PEP8 (coding conventions)
PEP stands for Python Enhancement Proposal. PEP8 is a document that outlines coding conventions (style guide) for Python. Recommended rules for comments using # are also described.
Following PEP8's rules is not necessary for avoiding syntax errors, but it is a good idea to adhere to PEP8 when there are no specific coding conventions for an organization or project.
The rules for writing comments, as well as the corresponding error codes used by code checkers like pydocstyle and flake8, are shown below.
Inline comments
E261: at least two spaces before inline comment
Place at least two spaces before the # in an inline comment. Three or more spaces are also acceptable, but only for aligning comments. Unnecessary spaces should be avoided.
# No:
a = 1 # comment
# Yes:
a = 1 # comment
a = 1 # comment
xyz = 100 # comment
E262: inline comment should start with '# '
Start an inline comment with a single space after the #. Do not omit the space or use more than one space.
# No:
a = 1 #comment
a = 1 # comment
# Yes:
a = 1 # comment
Block comments
E265: block comment should start with '# '
Start a block comment with a single space after the # unless the text is indented within the comment. Do not omit the space.
Unlike E262, two or more spaces are acceptable, but only for indentation within the comment. Unnecessary spaces should be avoided.
# No:
#comment
# Yes:
# comment
# indented comment
E266: too many leading '#' for block comment
Use only one leading #.
# No:
## comment
# Yes:
# comment
Using triple quotes as multiline comments
Docstrings can be added at the beginning of a function or class to provide explanations.
def test(a, b):
'''docstring
description
'''
print(a)
print(b)
Because triple quotes (either ''' or """) can create multiline strings, including line breaks, they are often used for docstrings.
Sometimes, triple quotes are used for multiline comments or to comment out a block.
a = 1
'''
b = 2
c = 3
d = 4
'''
e = 5
However, keep in mind that triple quotes create strings, not comments, so they are not ignored during execution like comments with #.
For example, when using triple quotes as comments within an indented block, you must ensure the indentation level is consistent, or you'll encounter an error.
If the indentation is properly matched, the code will work.
def test(a, b):
print(a)
'''
comment line1
comment line2
comment line3
'''
print(b)
If the indentation is incorrect, you'll get an IndentationError.
def test(a, b):
print(a)
'''
comment line1
comment line2
comment line3
'''
print(b)
# IndentationError: unexpected indent
Comments using # are ignored during execution, so incorrect indentation won't cause an error. However, for better code readability, it's recommended to maintain consistent indentation levels.
def test(a, b):
print(a)
# comment line1
# comment line2
# comment line3
print(b)
def test(a, b):
print(a)
# comment line1
# comment line2
# comment line3
print(b)
In any case, since triple quotes create strings rather than actual comments, it's safer to avoid using them as comments outside of docstrings.
Editors like VS Code use # for both single and multiline comments when using the comment-out shortcut (command + / or control + /).
Comments with function annotations
Since Python 3.0, function annotations can be used to add annotations, such as type information or descriptions, to function arguments and return values.
def func_annotations_type(x: str, y: int) -> str:
return x * y
Function annotations serve as notes, and specifying a type doesn't enforce type checking during execution. However, some IDEs and editors may utilize this information for various purposes.