¿Cómo comentar en Python?

Los comentarios son esenciales en el código Python para explicar su funcionamiento y facilitar su comprensión. Aprende las mejores prácticas sobre cómo comentar en Python y mejorar la legibilidad.

¿Cómo comentar en Python?: Los comentarios

Los comentarios son como notas personales en tu código, destinadas a ti mismo y a otros programadores que puedan leerlo en el futuro. Además de ayudar a explicar el propósito y la lógica detrás de un fragmento de código, también pueden servir como recordatorios útiles para futuras actualizaciones o modificaciones.

Comentarios inline

Los comentarios inline son perfectos para aprender cómo comentar en Python ya que pueden proporcionar aclaraciones rápidas y concisas sobre partes específicas de tu código. Por ejemplo, si tienes una línea que realiza una operación matemática un tanto complicada, puedes usar un comentario inline para explicar brevemente qué está haciendo esa línea para que otros puedan entenderla más fácilmente sin tener que profundizar en el código.

#¿Cómo comentar en Python?
# Incrementa el valor de x en 10
x = x + 10  # Make offset of 10px

Comentarios block

Los comentarios block, por otro lado, son ideales para explicar secciones más extensas de tu código o para proporcionar una visión general del propósito de un bloque de código completo, son otras de las opciones para aprender cómo comentar en Python. Estos comentarios suelen situarse encima del bloque de código al que hacen referencia, permitiendo al lector comprender rápidamente qué hace ese bloque sin necesidad de examinar cada línea individualmente.

Ya sea que estés trabajando en un proyecto personal o en un equipo de desarrollo, los comentarios son una herramienta invaluable para comunicar tus ideas y hacer que tu código sea más accesible y comprensible para todos los involucrados.

#¿Cómo comentar en Python?
import csv
from itertools import groupby

# Obtiene una lista de nombres de un archivo CSV
with open('nombres.csv') as f:
    file_csv = csv.reader(f)

# Salta la parte del encabezado: (sr, nombre, perc)
header = next(file_csv)
    
# Solo el nombre de (número, nombre, perc)
personas = [ x[1] for x in file_csv]

# Ordena la lista por la primera letra porque 
# La función groupby busca datos secuenciales.
personas.sort(key=lambda x:x[0])
data = groupby(personas, key=lambda x:x[0])

# Obtener cada nombre como una lista 
data_grouped = {}
for k, v in data:
    # Obtener datos en la forma 
    # {'A' : ["Anthony", "Alex"], "B" : ["Benjamin"]}
    data_grouped[k] = list(v)

Comentarios multilínea

En Python, aunque no hay una sintaxis específica para los comentarios multilínea, existen varias formas de lograr este efecto. Una de las formas más comunes es utilizar varias líneas de comentarios inline, precediendo cada línea con el símbolo #. Esto es útil cuando quieres comentar varias líneas de código de forma rápida y sencilla.

Otra técnica consiste en utilizar cadenas de texto multilínea, encerrándolas entre tres comillas simples o tres comillas dobles. Aunque esta técnica no está destinada específicamente para comentarios, es comúnmente utilizada como tal, ya que Python ignora estas cadenas de texto cuando se ejecuta el código.

Los comentarios multilínea son especialmente útiles cuando necesitas explicar fragmentos extensos de código o proporcionar documentación detallada sobre una función o clase. Al escribir comentarios multilínea, es importante mantener un estilo claro y conciso para garantizar que el código sea fácil de entender para otros programadores que puedan leerlo en el futuro.

#¿Cómo comentar en Python?
print("Comentario Multilínea")
"""
Este
es un
Comentario
Multilínea
"""

Comentarios especiales

Además de los comentarios regulares que explican el funcionamiento del código, Python también ofrece algunos tipos de comentarios especiales que tienen propósitos específicos.

Comentarios Docstring de Python

Los docstrings son comentarios de varias líneas que se utilizan para documentar funciones, clases y módulos en Python. Estos comentarios están diseñados para ser leídos por humanos y también pueden ser utilizados por herramientas de generación de documentación para crear documentación automatizada.

Un docstring sigue una convención específica y proporciona información sobre el propósito de la función o clase, los argumentos que acepta, y cualquier valor de retorno que pueda generar. Es una práctica común incluir ejemplos de uso y cualquier otra información relevante que pueda ayudar a los usuarios a comprender cómo utilizar el código.

#¿Cómo comentar en Python?
def get_area(radius):
"""
Calculate the area of a circle.
Args:
    radius (float): The radius of the circle.

Returns:
    float: The area of the circle.

Example:
    >>> get_area(5)
    78.54
"""
return 3.14 * radius ** 2

Comentarios TODO

Los comentarios TODO se utilizan para marcar partes del código que necesitan ser completadas o mejoradas en el futuro. Estos comentarios son útiles para recordar tareas pendientes o áreas del código que requieren atención adicional. Los programadores suelen utilizarlos para señalar áreas donde se necesita más trabajo o para indicar posibles mejoras o optimizaciones que se pueden realizar más adelante.

#¿Cómo comentar en Python?
# TODO: Implement error handling for file I/O
def read_file(filename):
    pass

# TODO: Refactor this code for better performance
def optimize_code(data):
    pass

Es importante tener en cuenta que los comentarios TODO deben utilizarse con moderación y que no deben permanecer en el código de forma indefinida. Es recomendable revisar periódicamente los comentarios TODO y abordar las tareas pendientes para mantener el código limpio y bien mantenido.

¡Aprende a comentar tu código Python como un profesional y lleva tus habilidades de programación al siguiente nivel!

¿Quieres aprender a programar y convertirte en un desarrollador experto? Únete al Bootcamp en programación inicial de KeepCoding y descubre cómo el sector tecnológico puede transformar tu carrera profesional. ¡Inscríbete ahora y cambia tu vida!