Python 简明教程
Python - Comments
Python Comments
Python 注释是 Python 源代码中面向编程人员的说明或注解。它们被添加到源代码中,目的是让程序员更容易理解,并被 Python 解释器忽略。注释增强了代码的可读性,并帮助程序员非常仔细地理解代码。
Python comments are programmer-readable explanation or annotations in the Python source code. They are added with the purpose of making the source code easier for humans to understand, and are ignored by Python interpreter. Comments enhance the readability of the code and help the programmers to understand the code very carefully.
Example
如果我们执行下面给出的代码,则输出结果将简单地向控制台打印 “Hello, World!”,因为注释被 Python 解释器忽略,并且不影响程序的执行 −
If we execute the code given below, the output produced will simply print "Hello, World!" to the console, as comments are ignored by the Python interpreter and do not affect the execution of the program −
# This is a comment
print("Hello, World!")
Python 支持如下所示的三种注释类型 −
Python supports three types of comments as shown below −
-
Single-line comments
-
Multi-line comments
-
Docstring Comments
Single Line Comments in Python
Python 中的单行注释以哈希符号 (#) 开头,并一直延伸到行的结尾。它们用于提供关于代码的简短说明或注释。它们可以放在它们描述的代码上方单独的一行,也可以放在代码行末尾(称为内联注释),以提供关于该特定行的注释或阐述。
Single-line comments in Python start with a hash symbol (#) and extend to the end of the line. They are used to provide short explanations or notes about the code. They can be placed on their own line above the code they describe, or at the end of a line of code (known as an inline comment) to provide context or clarification about that specific line.
Example: Standalone Single-Line Comment
独立的单行注释是一条注释,它独自占据一行,以哈希符号 (#) 开头。它被放在它描述或标注的代码上面。
A standalone single-line comment is a comment that occupies an entire line by itself, starting with a hash symbol (#). It is placed above the code it describes or annotates.
在此示例中,独立的单行注释被放在“greet”函数上面 −
In this example, the standalone single-line comment is placed above the "greet" function "−
# Standalone single line comment is placed here
def greet():
print("Hello, World!")
greet()
Example: Inline Single-Line Comment
内联单行注释是出现在与代码同一行上、跟随代码和以哈希符号 (#) 开头的注释。
An inline single-line comment is a comment that appears on the same line as a piece of code, following the code and preceded by a hash symbol (#).
在此处,内联单行注释跟随 print("Hello, World!") 语句 −
In here, the inline single-line comment follows the print("Hello, World!") statement −
print("Hello, World!") # Inline single line comment is placed here
Multi Line Comments in Python
在 Python 中,多行注释用于提供跨越多行的较长说明或注释。Python 虽然没有多行注释的专门语法,但有两种常见方法来实现这一点:连续的单行注释和三引号字符串 −
In Python, multi-line comments are used to provide longer explanations or notes that span multiple lines. While Python does not have a specific syntax for multi-line comments, there are two common ways to achieve this: consecutive single-line comments and triple-quoted strings −
Consecutive Single-Line Comments
连续的单行注释是指在每行的开头使用哈希符号 (#)。该方法通常用于较长的说明或将代码的某些部分分隔开。
Consecutive single-line comments refers to using the hash symbol (#) at the beginning of each line. This method is often used for longer explanations or to section off parts of the code.
Example
在此示例中,多行注释用于说明阶乘函数的目的和逻辑 −
In this example, multiple lines of comments are used to explain the purpose and logic of the factorial function −
# This function calculates the factorial of a number
# using an iterative approach. The factorial of a number
# n is the product of all positive integers less than or
# equal to n. For example, factorial(5) is 5*4*3*2*1 = 120.
def factorial(n):
if n < 0:
return "Factorial is not defined for negative numbers"
result = 1
for i in range(1, n + 1):
result *= i
return result
number = 5
print(f"The factorial of {number} is {factorial(number)}")
Multi Line Comment Using Triple Quoted Strings
我们可以使用三引号字符串(''' 或 "")来创建多行注释。从技术上来说,这些字符串是字符串字面量,但如果它们未分配给任何变量或在表达式中使用,则它们可以用作注释。
We can use triple-quoted strings (''' or """) to create multi-line comments. These strings are technically string literals but can be used as comments if they are not assigned to any variable or used in expressions.
此模式通常用于块注释或在需要详细说明的代码部分编制文档时。
This pattern is often used for block comments or when documenting sections of code that require detailed explanations.
Example
在此处,三引号字符串对“gcd”函数提供了详细说明,描述了其目的和所使用的算法 −
Here, the triple-quoted string provides a detailed explanation of the "gcd" function, describing its purpose and the algorithm used −
"""
This function calculates the greatest common divisor (GCD)
of two numbers using the Euclidean algorithm. The GCD of
two numbers is the largest number that divides both of them
without leaving a remainder.
"""
def gcd(a, b):
while b:
a, b = b, a % b
return a
result = gcd(48, 18)
print("The GCD of 48 and 18 is:", result)
Using Comments for Documentation
在 Python 中,文档注释(也称为文档字符串)提供了在代码中合并文档的方法。这对于说明模块、类、函数和方法的目的和用法非常有用。有效地使用文档注释可以帮助其他开发人员在不需要通读实现的所有细节的情况下理解你的代码及其目的。
In Python, documentation comments, also known as docstrings, provide a way to incorporate documentation within your code. This can be useful for explaining the purpose and usage of modules, classes, functions, and methods. Effective use of documentation comments helps other developers understand your code and its purpose without needing to read through all the details of the implementation.
Python Docstrings
在 Python 中,文档字符串是一种特殊的注释,用于记录模块、类、函数和方法。它们是用三引号(‘‘‘‘或“””)编写的,在它们所记录的实体定义之后立即放置。
In Python, docstrings are a special type of comment that is used to document modules, classes, functions, and methods. They are written using triple quotes (''' or """) and are placed immediately after the definition of the entity they document.
可以以编程方式访问文档字符串,这使得它们成为 Python 内置文档工具的重要组成部分。
Docstrings can be accessed programmatically, making them an integral part of Python’s built-in documentation tools.
Example of a Function Docstring
Example of a Function Docstring
def greet(name):
"""
This function greets the person whose name is passed as a parameter.
Parameters:
name (str): The name of the person to greet
Returns:
None
"""
print(f"Hello, {name}!")
greet("Alice")
Accessing Docstrings
可以使用 . doc 特性或 help() 函数来访问文档字符串。这使得可以从交互式 Python shell 或代码中直接查看任何模块、类、函数或方法的文档。
Docstrings can be accessed using the .doc attribute or the help() function. This makes it easy to view the documentation for any module, class, function, or method directly from the interactive Python shell or within the code.
Example: Using the .doc attribute
Example: Using the .doc attribute
def greet(name):
"""
This function greets the person whose name is passed as a parameter.
Parameters:
name (str): The name of the person to greet
Returns:
None
"""
print(greet.__doc__)
Example: Using the help() Function
Example: Using the help() Function
def greet(name):
"""
This function greets the person whose name is passed as a parameter.
Parameters:
name (str): The name of the person to greet
Returns:
None
"""
help(greet)