Cómo comentar un bloque de código en Python

Los comentarios son una de las herramientas más útiles cuando se trabaja con Python. Nos guían por la lógica, las decisiones y los propósitos que hay detrás de los bloques de código, sin interferir en la ejecución. Los comentarios ayudan a que el código sea más legible y mantenible, y facilitan la colaboración en un entorno de equipo.

Este tutorial profundizará en dos métodos eficaces para comentar varias líneas de código en Python, para garantizar que tu código esté bien documentado y sea fácilmente comprensible.

¿Por qué son importantes los comentarios en bloque en Python?

Los comentarios suelen ser uno de los primeros conceptos que encuentras en tu viaje de aprendizaje de Python. Proporcionan un contexto útil sobre la intención de un determinado fragmento de código. Ofrecen claridad y contexto sobre por qué un guión se comporta como lo hace. Hay varias razones importantes por las que siempre debes utilizar comentarios en tus guiones. Aquí tienes cuatro de ellas:

• Documentación: Los comentarios actúan como una forma de documentación que explica la finalidad de las funciones, clases o bloques de código. Esto es especialmente útil para algoritmos complejos en los que la lógica puede no ser inmediatamente evidente.
• Legibilidad: El código bien comentado es más fácil de leer y comprender. Esto es crucial cuando tú u otros reviséis el código después de algún tiempo.
• Depuración: Comentar temporalmente secciones de código es una práctica habitual para aislar e identificar errores.
• Colaboración: En un entorno de equipo, los comentarios hacen que el código sea más compartible y comprensible, para facilitar una colaboración y revisión del código más fluidas.

Usar comentarios de bloque de una sola línea en Python

Antes de sumergirnos en el comentario de varias líneas, empecemos por lo básico de los comentarios de una sola línea. En Python, un comentario de una sola línea comienza con el símbolo almohadilla (#), y el intérprete de Python ignora todo lo que le sigue en esa línea. Para crear un comentario de una sola línea, sigue las instrucciones que aparecen a continuación:

1. Colocación: Coloca el símbolo # al principio de la línea o después del código en la misma línea. Los comentarios pueden colocarse encima del código que describen, en la misma línea a la derecha del código, o independientes.
2. Contenido: Después del símbolo #, escribe tu comentario. Puede ser una explicación de la línea de código, una nota para futuras referencias o cualquier información útil relacionada con el código.

# This is a single-line comment explaining the next line of code
print("Hello, world!")  # This prints a message to the console

Método 1: Comentar utilizando varias líneas simples #

La forma más sencilla de comentar en Python es utilizar el símbolo #, que comenta todo lo que le sigue en la línea. Aunque Python no tiene una sintaxis específica para los comentarios en bloque, puedes utilizar varios símbolos # para comentar cada línea individualmente. Solo tienes que realizar los siguientes pasos:

1. Identifica el bloque de código: Primero, identifica el bloque de código que deseas comentar. Puede ser una función, un bucle o cualquier segmento de tu código que quieras desactivar o explicar.
2. Comenta cada línea: Coloca un símbolo # al principio de cada línea que quieras comentar. Esto indica al intérprete de Python que ignore estas líneas durante la ejecución.

Puedes ver el ejemplo a continuación:

# Example of commenting out multiple lines individually 
# def example_function(name):
#	# This function prints "Hello " and the input name
# 	print("Hello", name)

Método de comentario en bloque de Python n.º 2: Comentar utilizando literales de cadena entre comillas triples

Un método alternativo para comentar varias líneas es utilizar literales de cadena entre comillas triples (''' ''' o """ """). Aunque oficialmente no son comentarios de bloque, estos literales de cadena se utilizan a menudo como tales, especialmente para comentarios de varias líneas o docstrings. Para utilizar cadenas entre comillas triples, simplemente coloca ''' o """ antes y después del bloque de código que desees comentar, como tal:

'''
def example_function(name):
	print("Hello", name)
'''

Los literales de cadena entre comillas triples son los más utilizados para documentar las funciones de Python. Por ejemplo:

# Create example_function()
def example_function(name):
	'''
	This function takes as input a name, and returns a salutation to the name in the form of "Hello name"
	'''
	# Print the output 
	print("Hello", name)

Estos literales de cadena entre comillas triplicadas se denominan cadenas de documentos; puedes leer más sobre ellos en nuestro tutorial sobre cadenas de documentos.

Reflexiones finales

Los comentarios son una parte indispensable para escribir código Python limpio, mantenible y colaborativo. Tanto si utilizas comentarios de una línea con # como comentarios de varias líneas con cadenas entre comillas triples, el objetivo es mejorar la legibilidad y comprensión de tu código.

Para leer más y profundizar en tus conocimientos sobre las mejores prácticas de programación en Python, consulta los siguientes recursos:

• Programa de habilidades Fundamentos de Python
• 6 buenas prácticas de Python para un código mejor
• Documentar el código Python: guía práctica