Blog
La capacidad de comentar el código fuente figura en todos los lenguajes de programación. Un comentario es una línea de texto no ejecutable, esto quiere decir que el compilador o intérprete no la tomará como una línea de código. Los comentarios en Python, así como en otros lenguajes de programación, sirven para dejar pequeñas explicaciones sobre qué es lo que hace el programa. Sabemos que es muy difícil recordar cada aspecto de nuestro programa, sobre todo cuando trabajamos en proyectos largos y complicados. Python, al ser un lenguaje sencillo en cuestiones de sintaxis, nos ayuda a documentar apropiadamente nuestro código sin mucho esfuerzo. Esta es una práctica necesaria y los buenos desarrolladores harán un gran uso de los comentarios. Sin esto, el código fuente puede volverse confuso realmente rápido.
En Python hacer comentarios de dos formas:
- Escribiendo el símbolo de numeral (#) al comienzo de la línea de texto donde queremos nuestro comentario.
- Escribiendo triple comilla (‘) al principio y al final del comentario, en este caso los comentarios pueden ocupar mas de una línea.
Veamos un par de ejemplos:
-
Comentarios de una sola línea en Python.
# Esto es un comentario en Python >>> funcion_1() >>> funcion_2() # Los comentarios también pueden estar después de un texto ejecutable # Este es otro comentario en Python. # Puedes tener tantos comentarios de línea simple seguidos.
-
Comentarios multilínea en Python.
"""Este es un comentario multilínea. Podemos escribir tantas líneas queramos a modo de documentación.""" funcion_3() funcion_4() '''También podemos hacer comentarios multilíneas con comillas simples.'''
Docstrings
Python cuenta con otra herramienta para ayudar a los desarrolladores a documentar su código, las docstrings. Estas son simplemente comentarios multilínea ubicados después de la declaración de una función. Estas proveen una forma conveniente de documentar funciones, módulos, clases y métodos en Python.
Ejemplo:
def funcion_1(a, b): '''Esta funcion retorna la suma de ambos argumentos.''' return a + b
Ten en cuenta algunas convenciones al hacer comentarios en tu código fuente en Python:
- No satures tu código con comentarios de una sola línea.
- Los comentarios de una sola línea deben estar separados al menos dos espacios del signo de comentario (#).
- Úsalos cuando de verdad los creas necesario, no comentes código que es fácil de entender.
Ejemplo de comentarios en Python en un caso real
Veamos directamente el uso de los docstrings y comentarios en Python. El siguiente script le pide al usuario que ingrese el primer nombre de un estudiante en clase, hasta que se ingrese una string vacía. Luego la función imprime el número de estudiantes con cada nombre que se ingresó.
def nombres(): '''Pide al usuario que ingrese el primer nombre de un estudiante en clase hasta que se ingrese una string vacía. Luego la función imprime el número de estudiantes con cada nombre que se ingresó. ''' nombre = '' nombres = [] nombre = input('Enter next nombre: ') while nombre != '': # Mientras que nombre no sea una string vacia nombres.append(nombre) nombre = input('Enter next nombre: ') # Creamos un diccionario con la estructura nombre:ocurrencias ocurrencias_nombre = {n:nombres.count(n) for n in nombres} # Iteramos a traves de las claves del diccionario for k in ocurrencias_nombre.keys(): singular = True if ocurrencias_nombre[k] < 2 else False if singular: print('Hay {} estudiante llamado {}'.format(ocurrencias_nombre[k], k)) else: print('Hay {} estudiantes llamados {}'.format(ocurrencias_nombre[k], k)) nombres()
Debemos mantener nuestro código bien documentado y solo con comentarios que sean necesarios. Recuerda siempre agregar una docstring a tus funciones para tener siempre claro su objetivo.