Comentarios en Python
Hola, Mundo! - Parte 4: Agregando comentarios
Volvamos a recordar nuestro primer programa: "Hola, Mundo!":
A este programa le fuimos haciendo modificaciones hasta llegar a la siguiente versión:
Que al ejecutarse en la terminal de VS Code, mostraba el siguiente resultado:
Claramente es un programa pequeño, de tan solo 2 líneas de código, fácil de leer y comprender. Pero, ¿qué pasa si el programa es más largo? ¿Qué pasa si tiene 10, 20, 100 o incluso 1000 líneas de código? ¿Cómo sabrías qué hace cada parte del programa? ¿Cómo recordarías qué es lo que hace cada línea de código?
Por suerte, resulta que Python y muchos lenguajes de programación admiten algo llamado comentarios.
Antes de profundizar en este concepto, veamos como quedaría el programa anterior con comentarios:
A simple vista podemos observar que se agregaron 2 líneas al programa: Pregunta al usuario su nombre y luego Imprime el saludo personalizado. Ambas líneas tienen un símbolo al inicio # que las identifican como comentarios y en VS Code se ven en un color diferente (pueden aparecer en gris, verde o en el color que configures tu interfaz) al del código del programa. Esto es así para que puedas distinguirlas fácilmente. Y por supuesto, no afectan en nada a la ejecución del programa.
¿Qué son los comentarios?
En Python hablamos de comentarios como la inclusión de textos descriptivos breves junto con el código para describir el proceso de pensamiento mientras se escribe el código. Es decir, explica la lógica básica detrás de por qué se escribió una línea de código en particular, aumentando su legibilidad y comprensión.
En términos más simples, los comentarios son notas dentro de la escritura de un programa. Están destinados exclusivamente para el programador (vos, yo o cualquier persona que sepa leer código), y permiten explicar que es lo que hace cada fragmento de código, ya sea este una línea única o un bloque o conjunto de líneas, siempre que esta explicación sea digna de ser mencionada. Es decir, no hay que comentar cada línea de código a menos que valga la pena recordar su funcionamiento en el futuro o transmitir su funcionamiento a otros programadores. Además, son muy útiles cuando los programas son largos y complejos.
Así que no serían realmente necesarios para un programa tan pequeño como el nuestro, dado que es bastante obvio con sólo una, dos o tres líneas código determinar lo que está haciendo el programa. Además, es igual de rápido leer el código que los comentarios. Sin embargo:
¡Buena práctica!
Es importante adquirir el hábito de comentar el código es muy importante para vos y para el resto de los desarrolladores con quienes compartas tus programas.
¿Por qué?
* Porque mañana, o dentro de una semana, o dentro de un buen tiempo seguramente nos vamos a haber olvidado de lo que hacía ese fragmento de código;
* o porque si compartimos nuestro programa con otros programadores, los comentarios les facilitarían la compresión del funcionamiento sin necesidad de analizar todo el código;
* o porque al detectar un error en la ejecución del programa, leer cuál era el objetivo de la tarea o acción que debía realizar determinado código facilitaría analizar y corregir las fallas o validar si el código está funcionando correctamente;
* o simplemente porque queremos recordar por qué escribimos una línea de código de una manera en particular.
Cualquiera sea el caso, leer un comentario para comprender el código asociado resultará más simple que analizar el código en si.
Hasta acá hemos visto un ejemplo de nuestro programa con comentarios y el por qué es importante comentar nuestro código. Sin embargo, agregar comentarios no es solamente agregar una línea informativa a nuestros programas, así que exploremos en profundidad este concepto.
¿Para qué se usan los comentarios y cuáles son las ventajas?
Existen múltiples razones y ventajas para escribir comentarios en un programa:
-
aumentar la legibilidad: el código se explica por sí mismo
-
explicar el código a terceros: hacer que el código sea fácilmente comprensible para otros programadores
-
comprender el código fácilmente después de un largo período: ayudar a recordar por qué usamos un comando, método o función específica en el programa, por ejemplo
-
reutilizar el código existente: permite comprender el funcionamiento de un fragmento del programa para poder implementarlo en otra parte
-
evitar la ejecución de código: permite al intérprete ignorar alguna parte del código durante la ejecución del programa
¿Cómo escribir buenos comentarios en Python (y en general)?
Los comentarios son una parte crucial de un programa. De ahí que sea fundamental aprender a escribir buenos comentarios.
A continuación presentamos algunas características que definen los buenos comentarios.
-
Asegúrate de que sean concisos.
-
No escribas comentarios genéricos; solo si agregan información.
-
Escribe comentarios que describan la tarea general de una función o método; y no de detalles específicos.
-
Los buenos comentarios se explican por sí solos.
-
No escribas comentarios redundantes.