Comentarios en el código

5.1 Cómo escribir comentarios

En Python, como en muchos lenguajes de programación, se pueden escribir comentarios en el código. Los comentarios ayudan a los programadores y a otros participantes del proyecto a entender el código, lo cual es especialmente útil en el trabajo en equipo y en el mantenimiento a largo plazo de programas. En Python existen varias formas de añadir comentarios al código.

Comentarios de una sola línea:

Comienzan con el símbolo #. Todo lo que sigue después de # en la misma línea es ignorado por Python. Este tipo de comentarios se usa generalmente para observaciones breves o explicaciones sobre una línea específica de código. Ejemplo:

# Este es un comentario de una sola línea
print("Hello, World!") # Explicación de la acción de la función

Comentarios de múltiples líneas:

En Python, oficialmente no existe una sintaxis especial para comentarios de múltiples líneas, pero se pueden crear utilizando varios comentarios de una sola línea o usando comillas triples, aunque esto último es en realidad un literal de cadena de múltiples líneas, que no se ejecuta como código. Ejemplo:

# Este es un ejemplo de comentario de múltiples líneas
# Cada línea comienza con el símbolo #
      

o:

"""
Este es un literal de cadena de múltiples líneas que puede usarse como comentario.
Python lo interpreta como una cadena, pero no hace nada con ella,
a menos que se asigne a una variable o se use en una expresión.
"""
    
      

5.2 Por qué escribir comentarios

El uso de comentarios en el código mejora su legibilidad, facilita el mantenimiento y actualización, y también contribuye a una colaboración más efectiva en equipos. Los comentarios deben ser breves, pero informativos y relevantes, para servir como documentación útil del código y no llenarlo de información innecesaria.

Docstrings:

Son cadenas que usualmente se colocan al principio de módulos, clases, métodos y funciones para describir su propósito. Se encierran entre comillas triples dobles y pueden usarse para la generación automática de documentación.

Ejemplo:

def add(a, b):
"""
    Función para sumar dos números.
    :param a: primer sumando
    :param b: segundo sumando
    :return: suma de a y b
    """
    return a + b

En el mundo de la programación, a veces los desarrolladores añaden a su código comentarios que no solo sirven como explicaciones, sino que también arrancan una sonrisa. Aquí algunos ejemplos de comentarios divertidos que puedes encontrar en el código:

Ejemplo 1

 

            # Explicaría qué está pasando aquí, pero ya ni yo lo entiendo.
        

Ejemplo 2

 

    # Si esto no funciona, la culpa es de alguien más.

Ejemplo 3

 

    # Vine, vi, arreglé... y rompí.

Ejemplo 4

 

    # Cuando escribí esto, solo Dios y yo sabíamos cómo funciona. 
    # Ahora solo Dios lo sabe.

Estos comentarios pueden añadir ligereza y humor al proceso de desarrollo, haciendo la base de código menos monótona. También pueden servir como recordatorio de que el desarrollo de software es un proceso creativo y humano.

5.3 Comentar código rápidamente

En PyCharm puedes comentar o descomentar rápidamente el código utilizando atajos de teclado. Para ello, selecciona las líneas de código que quieras cambiar y presiona Ctrl + / en Windows (o Cmd + / en macOS). Esta combinación de teclas añade o quita el símbolo de comentario en cada línea seleccionada, haciendo el proceso rápido y eficiente.