La importancia de la documentación
En programación, el orden y la claridad, son dos de las partes fundamentales. Sin ellas, todo lo que hagas, será muy difícil de entender y mantener.
Imagina una biblioteca de Python, que no tenga documentación en absoluto, ni tutoriales. Solo el código.
Esto hará que tengas que utilizar otra biblioteca, en su lugar, o bien, que estés horas o días investigando como utilizar cada cosa.
Si tienes una documentación a mano, puedes consultar de forma rápida, todo lo que puedes hacer y como lo puedes hacer, errores y malas prácticas que se pueden evitar, etc.
No necesariamente hace falta que te la aprendas de arriba a abajo. Siempre la tendrás a mano para ir consultándola.
Diferencia entre comentar y documentar
Si bien podemos decir que cuando estamos comentando, también estamos documentando en cierto modo, hay que distinguir bien cada cosa. Los comentarios son pequeñas anotaciones en el código fuente, que son ignorados por el intérprete de Python.
Estas anotaciones sirven para dar una ayuda rápida de cosas sencillas. Normalmente, antes de ir a consultar la referencia de la documentación.
En cambio, la documentación es una descripción detallada
del software. Puede llevar mucha información
de gran utilidad. Cosas como requisitos, como está
diseñado, como utilizar cada una de sus herramientas, etc.
Ambas cosas deben utilizarse para proporcionar toda la información posible, y por supuesto, que sea útil. Más información en esta caso, no es necesariamente es mejor.
Los comentarios
Los comentarios en Python se crean con el caracter
#.
Estos comentarios ocupan una sola línea.
Para respetar la convención PEP 8 de Python, estos no deberían ocupar más de 72 caracteres de longitud. Si necesitas más, añade otro comentario debajo, o plantéate si realmente te tienes que extender tanto.
Aquí tienes un ejemplo de comentario de una línea:
# Multiplica con dos números
def multiplicar(a, b):
return a * bPropósitos de los comentarios
Los comentarios pueden tener varios propósitos, a continuación, tienes algunos:
Describir el código
Los comentarios son muy útiles para describir cosas de manera simple en el código. Por ejemplo:
# Esta función devuelve un resultado aleatorioPlanificación
También pueden servir para planificar los pasos en la creación de algo:
# Paso 1: Solicitar al usuario un número
# Paso 2: Convertir el número a un número entero
# Paso 3: Comprobar si el número es par o imparEtiquetado
Quizás hayas visto, en muchas ocasiones, palabras en
comentarios; palabras como TODO.
Estas etiquetas se pueden utilizar en los comentarios para explicar el código, marcar errores, tareas pendientes, etc. Son palabras que funcionan como convención, no son palabras clave ni nada parecido.
Algunas de las palabras que encontrarás, son estas (entre paréntesis las tienes traducidas al español):
BUG (FALLO)
Indica un error en el código que hay que revisar.
Ejemplo de uso:
# BUG: Este bucle genera mal los resultados cuando se usan valores negativos.
for i in range(maximo):
FIXME
Fix me (ARRÉGLAME)
Áreas de código problemático, errores, código mal hecho,
etc. Normalmente, no implican errores como los de
BUG. Más bien sirven para indicar cosas que hay que mejorar.
Ejemplo de uso:
# FIXME: La función es ineficiente, probar con una generadora
def procesar_valores(valores):
TODO
To do (PARA HACER)
Indica una tarea que aún no se ha completado o llevado a cabo. Se utiliza mucho para indicar cosas que hay que hacer en el futuro.
Ejemplo de uso:
# TODO: Implementar la función 'calcular_impuestos()'
NOTE (NOTA)
Indica una nota o comentario adicional.
Ejemplo de uso:
# NOTE: Mejora el rendimiento general. Manipular con cautela.
def procesador():
Estas etiquetas se utilizan mucho con los nombres de integrantes del equipo. Así, indicamos si el comentario va para alguien en concreto.
Por ejemplo:
# BUG(Ana): La función produce un fallo aleatorio.Con esto, le indicamos a Ana, que hemos encontrado un fallo que tiene que encargarse de revisar.
Comentarios con operador flecha
Desde la versión 3.5 (septiembre 2015) de Python, hay una forma explícita de mostrar un comentario especial, que indique el tipo de dato de retorno.
Realmente, no es un comentario estrictamente hablando, pero cumple su función.
Se trata del operador flecha o indicador de tipo de
retorno (->).
Gracias a este operador, podremos prescindir de comentarios como este:
# Acepta un str y devuelve un int
def longitud(cadena):
return len(cadena)En su lugar, podemos escribir esto:
def longitud(cadena: str) -> int:
return len(cadena)Con dos puntos podemos indicar el tipo de dato de los parámetros, y con el operador flecha, indicaremos explícitamente el valor de retorno de la función.
Esto es solo informativo, la función hará lo mismo en
ambos casos, pero ya de antemano, sabemos que se espera
que se le pase al parámetro cadena, un tipo de dato
str, y que su return, devuelve
un tipo de dato int.
def longitud(cadena: str) -> int:
return len(cadena)
print(type(longitud("Hola")))<class 'int'>Estos tipos de datos expresados explícitamente, no implican que se cree una obligación para pasar esos mismos.
Por ejemplo, en el lenguaje de programación Java, al crear los parámetros, indicamos los tipos de datos que van a llevar.
Si no les pasamos estos mismos tipos de datos en la llamada, recibimos un error. En Python, esto no ocurre, es mera información para quien desarrolla.
Parámetros con diferentes tipos de datos
Habrá veces en las que necesitemos pasar diferentes tipos de datos a un mismo parámetro. Entonces en estos casos, ¿cómo lo hacemos? La respuesta está en utilizar el tipo de dato object. Acuérdate de la superclase de todas las clases.
Aquí tienes un ejemplo:
def longitud(valor: object) -> float:
pass
También, ambos valores de entrada y salida pueden ser
object:
def longitud(valor: object) -> object:
passSi tienes varios argumentos, puedes indicar el tipo de cada uno:
def longitud(par1: object, par2: int, par3: float) -> float:
passLa función print()
La función print() de Python es un buen
ejemplo para mostrar como se utilizan estos comentarios en
código “real”.
def print(
*values: object,
sep: str | None = " ",
end: str | None = "\n",
file: SupportsWrite[str] | None = None,
flush: Literal[False] = False,
) -> None:
El primer parámetro es el que espera con
*args, que pasemos argumentos posicionales
arbitrarios (un número indefinido de ellos).
¿De qué tipo son los argumentos para *values?
Esta claro, lleva el comodín de todos los objetos con
object, puesto que puedes pasarle valores de
cualquier tipo.
Los parámetros sep y
end explícitamente indican que van a tener
valores str.
Lo que devuelve la función print() es un
valor None. Eso nos lo indica el operador
flecha.
Simplemente, imprime un print() con otro
print(), y lo verás:
print(print())None
Entonces, esto ya te da una pista de que poner cuando
crees una función que no tenga return, que
solo tenga print().
Aquí tienes un ejemplo:
def suma_decimales(a: float, b: float) -> None:
print(a + b)
suma_decimales(10.5, 20.4)30.9
Puede ser que este None te confunda, ya que en la consola
estás viendo un float. Sin embargo, este
float lo imprime el print(), no lo devuelve
la llamada.
Mira lo que devuelve realmente:
def suma_decimales(a: float, b: float) -> None:
print(a + b)
print(suma_decimales(10.5, 20.4))30.9
None
Un print() devuelve siempre un
None. Otra cosa es lo que imprime, pero eso
no es lo que hay que poner en la parte de retorno con el
operador flecha.
Mira otra forma de comprobarlo:
def suma_decimales(a: float, b: float) -> None:
print(a + b)
suma = suma_decimales(10.5, 20.4)
print(type(suma))30.9
<class 'NoneType'>
Ahora, reemplazamos el print() por
return:
def suma_decimales(a: float, b: float) -> float:
return a + b
suma = suma_decimales(10.5, 20.4)
print(type(suma))<class 'float'>Docstrings
Python también tiene la posibilidad de utilizar cadenas de caracteres literales como comentarios.
Estos se conocen muy a menudo como comentarios multilínea. La sintaxis es la siguiente:
"""
Comentario
de varias
líneas.
"""Estos pueden servir para comentarios algo más largos que los de una línea y documentar módulos, clases, métodos, funciones, etc.
No obstante, también se pueden utilizar como comentarios de una línea:
"""Una línea"""A estos comentarios los llamamos docstrings.
El término docstring es una conjunción de dos palabras: doc(umentation)-string, que podemos traducir al español como cadena de caracteres de documentación.
La función predefinida help()
Si ya la conocías, ¿te has preguntado alguna vez de donde
sale la información que obtenemos con la función
predefinida help()?
Abre el intérprete interactivo de Python.
Si tienes las variables de entorno configuradas correctamente, solo tendrás que abrir la consola, y escribir el siguiente comando:
pythonEsto abrirá el intérprete interactivo:
E:\Cursos\Python>python
Python 3.12.1 (tags/v3.12.1:2305ca5, Dec 7 2023, 22:03:25) [MSC v.1937 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>>
En este caso, consultemos la ayuda de int:
>>> help(int)
Help on class int in module builtins:
class int(object)
| int([x]) -> integer
| int(x, base=10) -> integer
. . . Resto de las explicaciones . . .
Parte de esta ayuda de documentación, la puedes acceder
desde la hoja de código, con el atributo especial
__doc__.
Especifica un objeto y utiliza el atributo
__doc__:
print(int.__doc__)
A donde quiero llegar, es que con las docstrings,
podrás documentar elementos de tu código, y que queden
incluidos en los atributos __doc__ de los
objetos. De esa forma, crearás objetos documentados.
Aquí tienes un ejemplo:
def par_impar(numero):
"""
Solicita un número al usuario con input().
Lo transforma a tipo int.
Indica en la consola si el número es par o impar.
"""
numero = int(numero)
if numero % 2 == 0:
print("El número es par.")
else:
print("El número es impar.")
par_impar(7)El número es impar.Ten en cuenta que la docstring, debe respetar las indentaciones como el resto de elementos.
Ahora, vamos a imprimir la docstring en la consola:
print(par_impar.__doc__)Solicita un número al usuario con input().
Lo transforma a tipo int.
Indica en la consola si el número es par o impar.
También, puedes acceder al docstring utilizando la función
predefinida help():
help(par_impar)help on function par_impar in module __main__:
par_impar(numero)
Solicita un número al usuario con input().
Lo transforma a tipo int.
Indica en la consola si el número es par o impar.Los tipos de docstring
Encontrarás diversos tipos de docstrings. Algunas de ellas, son las de clase, las de método, las de función, las de paquete, las de módulo, etc.
En Visual Studio Code, la extensión Pylint te informa de las diferentes docstrings que tienes que especificar a medida que escribes código.
En la siguiente imagen puedes verlo:
Missing {type of element} docstring significa en español “falta {tipo de elemento} la cadena de documentación.”
La extensión Pylint no se actualiza en tiempo real, tienes que guardar cambios para que se actualicen los avisos.
Las docstrings, las iremos colocando al principio de cada elemento.
Aquí tienes un ejemplo:
""" docstring del módulo """
class Clase:
""" docstring de la clase """
def metodo(self):
""" docstring del método """
def funcion():
""" docstring de la función """Una vez incluyes una docstring en un elemento con bloque de código, no es necesario que incluyas la palabra reservada
passpara evitar errores al ejecutar con bloques “vacíos”.
Las docstrings, a diferencia de los comentarios de una línea, deben indentarse correctamente, de la misma forma que si fuesen otro elemento más en el código:
print("hola") """Docstring mal indentada"""Error en la consolaIndentationError: unexpected indentError de indentación: indentación inesperada
Espacio publicitario
Espacio publicitario