Cómo comentar en Python

Actualizado en julio de 2021

Introducción

Una habilidad clave en la escritura de código es la capacidad de usar comentarios. Los comentarios son líneas que los compiladores e intérpretes ignoran y que los desarrolladores usan para dejar notas sobre la función del código. Además, también se pueden usar para deshabilitar partes del código.

Esta guía le mostrará cómo usar los comentarios en Python de manera efectiva.

Requisitos previos

• Un entorno de programación Python en funcionamiento
• La capacidad de crear y editar archivos de Python

Sintaxis de comentarios de Python

Para agregar o marcar una línea como comentario, comience con un signo de almohadilla. (# ) y un espacio :

# This is a sample comment.

El uso de la almohadilla para iniciar la línea le dice al sistema que ignore todo lo que hay en esa línea. Cuando se ejecuta la aplicación, el programa finge que esas líneas no existen. Sin embargo, aún puede verlo cuando edita el archivo.

Por ejemplo, en el Hola Mundo programa a continuación:

# Display the text "Hello, World!" on the screen.
print("Hello, World!")

El sistema ejecuta el código print("Hello, World") en la línea cuatro, mientras que la línea superior explica lo que se supone que debe hacer el código.

Puede establecer cualquier línea como comentario y usar tantas como desee. Si su código tiene diferentes bloques, puede usar un comentario para explicar cada uno. Por ejemplo:

# Define a variable flowers as a list of strings.
flowers = [‘rose’, ‘carnation’, ‘daisy’, ‘marigold’, ‘tulip’, ‘sunflower’]

# Create a for loop to iterate through flowers list, and displays each string item.
for flower in flowers:
            print(flower)

Bloque de comentarios de Python

Bloquear comentarios son comentarios de formato más largo que constan de varias líneas seguidas. Un desarrollador los usa para explicar código más complejo, especialmente cuando trabaja en equipo.

Para marcar una serie de líneas como un comentario, agregue un signo de almohadilla + espacio al principio de cada línea:

# This is a comment
# that runs on to
# multiple lines.

Algunos editores de texto o código para programación (como Notepad++ o Atom) le permiten resaltar el texto y luego hacer clic con el mouse para marcar el bloque como un comentario. Estas herramientas pueden ahorrarle tiempo al comentar cada línea.

Comentario multilínea de Python

En general, se recomienda usar # al comienzo de cada línea para marcarlo como un comentario. Sin embargo, comentar una sección grande lleva mucho tiempo y es posible que necesite una forma rápida de comentar una sección completa. En tales casos, puede usar comentarios de varias líneas .

Las cadenas de varias líneas no funcionan como los comentarios tradicionales de Python, ya que no existe una funcionalidad oficial de varias líneas. En su lugar, utilice cadenas de varias líneas entre comillas triples. (""" ) para lograr una función similar.

Por ejemplo:

def addition_test(a, b):
    result = a + b
    """
    This is a block
    of commented lines.
    They aren’t parsed and interpreted by the compiler.
    """
return result

Este método crea una constante de texto sin función, no un comentario verdadero. Mientras no agregue nada que acceda a esa cadena de texto, funciona igual que un comentario normal.

Las comillas triples pueden ser complicadas porque, en algunas circunstancias, crean una cadena de documentación si una comilla triple:

• sigue una firma de función,
• sigue una definición de clase,
• está al comienzo de un módulo.

Si coloca """ en uno de los lugares enumerados anteriormente, Python lo lee como dosctring . Docstrings le permite poner texto legible por humanos en el proyecto. Esto generalmente se usa para crear documentación que es parte de la aplicación y se puede acceder en tiempo de ejecución.

Comentario en línea de Python

Puede comentar en la misma línea que un fragmento de código usando un comentario en línea . El mejor momento para usar esta opción es cuando se explica una operación complicada.

Use un comentario en línea para señalar el lugar exacto que desea aclarar. Agregue el signo de almohadilla estándar + espacio para indicar un comentario en línea:

function
    set variable
    run command
    run additional command        # Tricky part:  The program breaks if this line is removed.

Los comentarios en línea se utilizan para agregar contexto a las personas que leen el código. Por ejemplo, puede explicar el propósito de una variable o dejar una nota sobre el tipo de variable creada. También puede ser útil explicar por qué se usa un comando en particular, como en el ejemplo anterior.

Comentar Python

Debido a que los comentarios hacen que el texto sea invisible para el analizador, puede usarlos para deshabilitar comandos. Si lo hace, le permite probar segmentos de código con y sin nuevas adiciones.

Por ejemplo, en este sencillo programa de lanzamiento de dados, hay una sección comentada. Si elimina el signo de hash, habilita el código para probarlo.

import random
min = 1
max = 6

roll_again = "yes"

while roll_again == "yes" or roll_again == "y":
     print "Rolling the dice..."
     print "The values are...."
     print random.randint(min, max)
     print random.randint(min, max)

# Add two random numbers together for a sum
# while roll_again == “yes” or roll_again == “y”:
    # print ”Rolling the dice…”
    # print “You rolled a “
    # print random.randint(min,max) + random.randint(min, max)

    roll_again = raw_input("Roll the dice again?")

¿Por qué son importantes los comentarios en Python?

Comentar puede ayudarte a:

• Comprenda su propio código cuando regrese a él después de un período de tiempo más largo.
• Vuelve a ponerte al día más rápido.
• Problemas de depuración.
• Comprender ciertas opciones de código cuando se trabaja dentro de un equipo.
• Evite posibles problemas al enfatizar por qué una parte específica del código es importante.

Prácticas recomendadas para los comentarios del código Python

• Comenta con la misma sangría que el código al que te refieres. Esto hace que sea más fácil ver a qué te refieres.
• Actualice sus comentarios cuando actualice su código. Los comentarios incorrectos son peores que ningún comentario.
• Use oraciones completas. Escriba con mayúscula las palabras apropiadas, a menos que se refiera a un identificador (como una variable). Nunca cambie el caso de un identificador.
• Los comentarios de bloque deben escribirse en oraciones completas, con puntos. Apunta a 80 palabras por línea o menos.
• Si tiene varias oraciones en un comentario, use un doble espacio entre oraciones.
• Escribe comentarios en inglés.
• Para un comentario de bloque con varios párrafos, agregue una línea en blanco entre los párrafos con una sola etiqueta de comentario antes de una línea en blanco.
• Para comentarios en línea, deje al menos dos espacios entre el código y el comentario. Use comentarios en línea con moderación y evite usarlos para decir lo obvio.

EVITAR:

• No comente el código que se explica por sí mismo. Cíñete al principio de escribir SECO (D no R repetir Y nosotros mismos) y evitar WET (W rito E todo T wice) código y comentarios.
• Evite usar comentarios para explicar el código desordenado:los comentarios deben admitir el código, no justificarlo.