Comentarios en Python3
En Python, los comentarios no afectan la ejecución del programa, pero hacen que el código sea más fácil de leer y entender.
En Python existen los siguientes tipos de comentarios:Comentarios de una sola líneayComentarios de varias líneas。
Comentarios de una sola línea
En Python, los comentarios de una sola línea se escriben con#al principio,#Todo el texto después del símbolo se considera un comentario y no será ejecutado por el intérprete.
Ejemplo
print("Hello, World!")
# Esto también es un comentario
Comentarios de varias líneas
En Python, las cadenas de varias líneas (bloques de texto delimitados por tres comillas simples'''o tres comillas dobles""") pueden usarse como comentarios de varias líneas.
1. Usar tres comillas simples
Ejemplo
'''
Este es un comentario multilínea, usando tres comillas simples
Este es un comentario multilínea, usando tres comillas simples
Este es un comentario multilínea, usando tres comillas simples
'''
print("Hello, World!")
2. Usar tres comillas dobles
Ejemplo
"""
Este es un comentario multilínea, usando tres comillas dobles
Este es un comentario multilínea, usando tres comillas dobles
Este es un comentario multilínea, usando tres comillas dobles
"""
print("Hello, World!")
Nota: Aunque las cadenas de varias líneas se usan aquí como comentarios de varias líneas, en realidad son cadenas; mientras no las usemos, no afectarán la ejecución del programa.
Estas cadenas se pueden colocar en ciertas posiciones del código sin que se ejecuten realmente, logrando así el efecto de un comentario.
Notas sobre los comentarios de varias líneas
En Python, los comentarios de varias líneas se definen mediante tres comillas simples'''o tres comillas dobles""", yEste tipo de comentario no se puede anidar.。
Cuando comienzas un bloque de comentario de varias líneas, Python tratará todas las líneas siguientes como comentario hasta encontrar otro grupo de tres comillas simples o tres comillas dobles.
Anidar comentarios de varias líneas provocará un error de sintaxis:
Ejemplo (ejemplo incorrecto)
Este es un comentario multilínea externo
Puede contener algún contenido descriptivo
'''
Este es un comentario multilínea que intenta anidarse
Causará un error de sintaxis
'''
'''
En este ejemplo, las tres comillas simples internas no se reconocen correctamente como el final del comentario de varias líneas, sino que se interpretan como una cadena normal, lo que provoca una estructura de código incorrecta.
Forma correcta: usar comentarios de una sola línea anidados
Ejemplo (ejemplo correcto)
Este es un comentario multilínea externo
Puede contener algún contenido descriptivo
# Este es un comentario interno de una sola línea
# Se puede anidar dentro de comentarios multilínea
'''
Docstring (cadena de documentación)
El Docstring (cadena de documentación) de Python es un tipo especial de comentario que se utiliza para añadir documentación a funciones, clases, módulos, etc. Es similar al Javadoc de Java, pero más potente y flexible.
A diferencia de los comentarios normales,el Docstring se puede__doc__acceder directamente mediante el atributo, o también se puede usar lahelp()función para verlo.
Sintaxis básica
El Docstring se escribe con tres comillas dobles"""o tres comillas simples'''que envuelven el texto, y se coloca al inicio de la función, clase o módulo.
Ejemplo
"""Devuelve la suma de dos números"""
return a + b
# Acceso a través del atributo __doc__
print(add.__doc__) # Salida: Devuelve la suma de dos números
Usar help() para ver la documentación
Ejemplo
"""Devuelve la suma de dos números"""
return a + b
# Usar la función help()
help(add)
Resultado esperado:
Help on function add in module __main__:
add(a, b)
返回两数之和
Usar el módulo inspect para extraer la documentación
La biblioteca estándar de Python proporcionainspectmódulo, que puede extraer directamente el contenido de la documentación:
Ejemplo
def add(a, b):
"""Devuelve la suma de dos números"""
return a + b
# Usar inspect.getdoc() para obtener la documentación
print(inspect.getdoc(add)) # Salida: Devuelve la suma de dos números
Resultado esperado:
Devuelve la suma de dos números
Docstring de varias líneas
Para funciones complejas, se puede usar un Docstring de varias líneas:
Ejemplo
"""
Realizar operaciones matemáticas
Parámetros:
a: el primer número
b: el segundo número
operation: tipo de operación, opciones "add", "subtract", "multiply"
Devuelve:
Resultado del cálculo
"""
if operation == "add":
return a + b
elif operation == "subtract":
return a - b
elif operation == "multiply":
return a * b
else:
raise ValueError("operación no soportada")
# Ver documentación completa
help(calculate)
Resultado esperado:
Help on function calculate in module __main__:
calculate(a, b, operation='add')
执行数学运算
Argumentos:
a: 第一个数字
b: 第二个数字
operation: 操作类型，可选 "add", "subtract", "multiply"
返回:
计算结果
Docstring de clases
El Docstring también se puede usar para clases:
Ejemplo
"""Clase Persona, utilizada para representar la información básica de una persona"""
def __init__(self, name, age):
"""
Inicializar el objeto Persona
Parámetros:
name: nombre
age: edad
"""
self.name = name
self.age = age
def introduce(self):
"""Presenta a esta persona"""
return fMe llamo {self.name} y tengo {self.age} años.
# Acceder a la documentación de la clase
print(Person.__doc__)
# Acceder a la documentación del método
print(Person.introduce.__doc__)
Resultado esperado:
Clase Persona, utilizada para representar la información básica de una persona Presentar a esta persona
Estándares de Docstring
En Python existen varios estilos de Docstring; los más comunes son:
- Estilo Google: utiliza sangría con espacios, y los parámetros y valores de retorno tienen etiquetas claras.
- Estilo Sphinx/reST: comienza con dos puntos, como
:param name:。 - Estilo NumPy: es similar al estilo Google, pero con un formato ligeramente diferente.
Se recomienda elegir un estilo en el proyecto y mantenerlo de forma consistente.
Otras extensiones