Cómo Escribir Comentarios en Python 3 (2023)

En este artículo, vamos a explorar cómo escribir comentarios en Python 3. Los comentarios son líneas que existen en los programas de computadora y son ignorados por los compiladores e intérpretes. El uso de comentarios en los programas puede hacer que el código sea más legible para los humanos, ya que proporciona información o explicación sobre lo que hace cada parte de un programa.

Comentarios en Python

En Python, los comentarios comienzan con un signo de numeral (#) y un espacio en blanco y continúan hasta el final de la línea. Por ejemplo:

# Esto es un comentario

Los comentarios no se ejecutan, por lo que cuando ejecutas un programa no verás ninguna indicación del comentario. Los comentarios están en el código fuente para que los humanos los lean, no para que las computadoras los ejecuten.

Comentarios en Línea

Los comentarios en línea ocurren en la misma línea de una declaración, después del código en sí. Por lo general, se utilizan para explicar partes complicadas o complejas del código. Por ejemplo:

x = 8  # Inicializar x con un número arbitrario

Los comentarios en línea deben usarse con moderación, pero pueden ser efectivos para explicar partes difíciles o complejas del código. También pueden ser útiles si crees que no recordarás una línea de código en el futuro, o si estás colaborando con alguien que puede no estar familiarizado con todos los aspectos del código.

Comentarios en Bloque

Los comentarios en bloque se pueden utilizar para explicar código más complicado o código con el que no se espera que el lector esté familiarizado. Estos comentarios de formato más largo se aplican a parte o a todo el código que sigue, y también están sangrados al mismo nivel que el código. Por ejemplo:

# La función principal analizará los argumentos a través de la variable del analizador. Estos
# argumentos serán definidos por el usuario en la consola. Esto pasará
# el argumento de palabra que el usuario quiere analizar junto con el nombre de archivo que el
# usuario quiere usar, y también proporcionará texto de ayuda si el usuario no
# pasa correctamente los argumentos.
def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("palabra", help="la palabra que se buscará en el archivo de texto.")
    parser.add_argument("nombre_archivo", help="la ruta al archivo de texto que se buscará.")
    ...

Los comentarios en bloque se utilizan típicamente cuando las operaciones son menos comprensibles y, por lo tanto, requieren una explicación más detallada. Debes tratar de evitar comentar en exceso el código y confiar en que otros programadores entenderán Python a menos que estés escribiendo para una audiencia en particular.

Comentarios para Pruebas

Además de utilizar comentarios como una forma de documentar el código, el signo de numeral también se puede utilizar para comentar código que no deseas ejecutar mientras estás probando o depurando un programa que estás creando. Es decir, cuando experimentas errores después de implementar nuevas líneas de código, es posible que desees comentar algunas de ellas para ver si puedes solucionar el problema exacto.

El uso del signo de numeral también te permite probar alternativas mientras determinas cómo configurar tu código. Por ejemplo, puedes estar decidiendo entre usar un bucle while o un bucle for en un juego de Python, y puedes comentar uno u otro mientras pruebas y determinas cuál puede ser el mejor enfoque.

import random

number = random.randint(1, 25)

# number_of_guesses = 0

for i in range(5):
    # while number_of_guesses < 5:
    print('Adivina un número entre 1 y 25:')
    guess = input()
    guess = int(guess)
    # number_of_guesses = number_of_guesses + 1

    if guess < number:
        print('Tu suposición es demasiado baja')
    if guess > number:
        print('Tu suposición es demasiado alta')
    if guess == number:
        break

if guess == number:
    print('¡Adivinaste el número!')
else:
    print('No adivinaste el número. El número era ' + str(number))

Comentar el código con el signo de numeral te permite probar diferentes métodos de programación y también te ayuda a encontrar la fuente de un error al comentar sistemáticamente y ejecutar partes de un programa.

Conclusión

El uso de comentarios dentro de tus programas de Python ayuda a que tus programas sean más legibles para los humanos, incluido tu futuro yo. Incluir comentarios relevantes y útiles puede facilitar la colaboración con otros en proyectos de programación y hacer que el valor de tu código sea más claro.

A partir de aquí, es posible que desees leer sobre las Docstrings de Python en PEP 257 para obtener más recursos sobre cómo documentar adecuadamente tus proyectos de Python.