Añadir Comentarios en Python

Introducción

En este laboratorio, aprenderá la importancia y la aplicación práctica de los comentarios en Python. Los comentarios son esenciales para hacer que su código sea comprensible, lo cual es crucial para el mantenimiento y la colaboración. Explorará diferentes tipos de comentarios, incluidos los comentarios de una sola línea y de varias líneas, y aprenderá a utilizarlos eficazmente para mejorar la legibilidad del código.

Comprender el Propósito de los Comentarios

Los comentarios son notas dentro de su código que son ignoradas por el intérprete de Python, pero que son valiosas para los lectores humanos. Ayudan a explicar la lógica, el propósito y cualquier detalle no obvio del código. Si bien una máquina ejecuta el código, son los humanos quienes deben leerlo y mantenerlo. Los buenos hábitos de comentario son esenciales para escribir programas limpios y comprensibles.

Comencemos con un script simple sin ningún comentario. En el WebIDE, localice el archivo purpose.py en el explorador de archivos del panel izquierdo y ábralo.

Agregue el siguiente código al archivo purpose.py:

x = 10
y = 20
z = x + y
print(z)

Guarde el archivo presionando Ctrl + S.

Para ejecutar el script, abra la terminal integrada en el WebIDE navegando al menú superior y seleccionando Terminal -> New Terminal. La terminal se abrirá en la parte inferior de la pantalla, y la ruta predeterminada es ~/project.

Ejecute el script ejecutando el siguiente comando en la terminal:

python purpose.py

Verá la salida del cálculo:

30

Este script es sencillo, pero en un programa más grande, podría no ser inmediatamente claro qué representan x, y y z. En el siguiente paso, agregaremos comentarios para hacer que este código sea más fácil de entender.

Usar Comentarios de Una Sola Línea

Los comentarios de una sola línea se utilizan para notas explicativas breves. En Python, un comentario de una sola línea comienza con el símbolo de almohadilla (#). El intérprete ignora todo lo que sigue al # en esa línea. Estos comentarios pueden colocarse en una línea separada para describir el código siguiente o en la misma línea que una instrucción para explicarla.

Modifiquemos el archivo purpose.py para incluir comentarios de una sola línea. Abra purpose.py en el editor y actualice su contenido al siguiente:

## This script calculates the sum of two numbers

x = 10  ## Assign the integer 10 to variable x
y = 20  ## Assign the integer 20 to variable y
z = x + y  ## Calculate the sum of x and y
print(z) ## Print the final result to the console

Guarde el archivo (Ctrl + S) y ejecútelo de nuevo desde la terminal:

python purpose.py

La salida será la misma que antes:

30

Como puede ver, los comentarios no cambiaron el comportamiento del programa. Sin embargo, el código ahora es mucho más legible. El primer comentario explica el propósito general del script, mientras que los comentarios en línea aclaran el papel de cada línea.

Usar Comentarios Multilínea

Para explicaciones más largas que abarcan varias líneas, puede utilizar un formato de comentario multilínea. Aunque Python no tiene una sintaxis específica para comentarios multilínea como algunos otros lenguajes, puede usar cadenas multilínea (multi-line strings) para este propósito.

Una cadena multilínea se crea encerrando el texto entre comillas triples, ya sean """...""" (dobles) o '''...''' (simples). Si esta cadena multilínea no se asigna a una variable, el intérprete de Python la ignorará, convirtiéndola efectivamente en un comentario. Esta es una convención común para escribir comentarios de bloque o documentación de funciones (docstrings).

Busque y abra el archivo multiline.py en el WebIDE. Agregue el siguiente código:

"""
This is a multi-line comment using triple double quotes.
This script demonstrates how to write comments that span
several lines to provide more detailed explanations.
"""

message = "Hello, Python learners!"
print(message)

Guarde el archivo y ejecútelo desde la terminal:

python multiline.py

Verá la siguiente salida:

Hello, Python learners!

El bloque de texto dentro de las comillas triples fue ignorado, y solo se ejecutó la instrucción print. Esta técnica es muy útil para proporcionar descripciones detalladas al principio de un archivo o antes de una función compleja.

Usar Comentarios de Declaración

Python también admite comentarios especiales conocidos como comentarios de declaración. Estos son procesados por el intérprete o el sistema operativo para configurar cómo se ejecuta el script. Dos ejemplos comunes son el shebang y la declaración de codificación (encoding declaration).

1. Shebang (#!): La línea shebang es la primera línea de un script. Indica a un sistema operativo tipo Unix qué intérprete usar para ejecutar el archivo. Para un script de Python 3, esto es típicamente #!/usr/bin/python3. Esto le permite ejecutar el script como un ejecutable independiente.

2. Declaración de Codificación (Encoding Declaration): Este comentario le indica al intérprete de Python qué codificación de caracteres debe usar para el archivo fuente. Es importante si su código contiene caracteres que no son ASCII. La declaración estándar para UTF-8 es ## -*- coding: utf-8 -*-. Debe colocarse en la primera o segunda línea del archivo.

Creemos un script que utilice ambos. Abra el archivo declaration.py en el editor y agregue el siguiente código:

#!/usr/bin/python3
## -*- coding: utf-8 -*-

## This script demonstrates declaration comments and non-ASCII characters.
print("Hello, World!")
print("你好，世界！") ## A greeting in Chinese

Guarde el archivo. Antes de poder ejecutar este script directamente, necesita hacerlo ejecutable. En la terminal, ejecute el comando chmod:

chmod +x declaration.py

Ahora, puede ejecutar el script directamente sin escribir primero python:

./declaration.py

La salida mostrará correctamente ambas líneas de texto, incluidos los caracteres chinos:

Hello, World!
你好, 世界!

La línea shebang permitió al sistema encontrar y utilizar el intérprete de Python 3, y la declaración de codificación aseguró que los caracteres no ASCII se manejaran correctamente.

Resumen

En este laboratorio, ha aprendido a añadir comentarios a su código Python. Practicó el uso de comentarios de una sola línea con # para notas breves, comentarios multilínea con """...""" para descripciones más largas, y comentarios de declaración especiales como el shebang y la declaración de codificación para configurar la ejecución del script. Al comentar su código de manera efectiva, lo hace más legible, mantenible y más fácil de entender para otros (y para su yo futuro).