Buenas prácticas¶

Estilo de codificación¶

Además de una correcta y ordenada estructura general que deben tener los programa, es conveniente mantener ciertas buenas prácticas de codificación y el estilo de codificación recomendado. Estas normas no son obligatorias, como lo es la propia sintaxis del lenguaje, pero conviene seguir las recomendaciones de los desarrolladores de Python para facilitar la lectura del programa y ayudar a encontrar posibles errores.

A continuación, se presentan algunas buenas prácticas relacionadas con es estilo de codificación:

Variables¶

Cuando sea posible, define variables con nombres que tengan algún sentido o que puedas identificar fácilmente, no importa que sean más largas. Por ejemplo, en un programa podríamos escribir:

In [1]:

a = 10.  
b = 3.5 
print("El volumen es %.1f" % (a*b))

a = 10. b = 3.5 print("El volumen es %.1f" % (a*b))

El volumen es 35.0

pero, ¿qué significan a y b? lo sabemos por el comentario (bien hecho), pero si más adelante nos encontramos con esas variables, tendremos que recordar cual es cual. Es mejor usar nombres con significado:

In [1]:

altura = 10.
base = 3.5
print("El volumen es %.1f" % (altura*base))

altura = 10. base = 3.5 print("El volumen es %.1f" % (altura*base))

El volumen es 35.0

Lineas de códigos¶

Las líneas de codigo no deben ser muy largas, como mucho 72 caracteres. Si se tiene una línea larga, se puede cortar con una barra invertida (\) y continuar en la siguiente línea:

In [4]:

print("Esta es una frase muy larga, se puede cortar con una \
       y seguir en la línea inferior.")

print("Esta es una frase muy larga, se puede cortar con una \ y seguir en la línea inferior.")

Esta es una frase muy larga, se puede cortar con una        y seguir en la línea inferior.

Comentarios¶

Los comentarios son muy importantes al escribir un programa. Describen lo que está sucediendo dentro de un programa, para que una persona que mira el código fuente no tenga dificultades para descifrarlo.

In [5]:

# esto es un comentario
print('Hola')

# esto es un comentario print('Hola')

Hola

También podemos tener comentarios multilíneas:

In [6]:

# Este es un comentario largo
# y se extiende
# a varias líneas

# Este es un comentario largo # y se extiende # a varias líneas

Identación¶

Dentro de paréntesis, corchetes o llaves, no dejar espacios inmediatamente dentro de ellos:

In [7]:

# no:  
lista_01 = [1, 2, 3,4, 5, 6,7, 8, 9,]

# no: lista_01 = [1, 2, 3,4, 5, 6,7, 8, 9,]

In [8]:

# si 
lista_01 = [
    1, 2, 3,
    4, 5, 6,
    7, 8, 9, 
]

# si lista_01 = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, ]

Aunque en Python se pueden hacer varias declaraciones en una línea, se recomienda hacer sólo una en cada línea:

In [9]:

# no
a = 10; b = 20

# no a = 10; b = 20

In [10]:

# si
a = 10
b = 20

# si a = 10 b = 20

Cuando se trabaja con lista, conjuntos y/o tuplas se recomienda poner en cada línea sus argumentos.

In [11]:

# no
lista = [(1, 'hola'),(2, 'mundo'),]

# no lista = [(1, 'hola'),(2, 'mundo'),]

In [12]:

# si
lista = [
    (1, 'hola'),
    (2, 'mundo'),
]

# si lista = [ (1, 'hola'), (2, 'mundo'), ]

Lo anterior se puede extender para funciones con muchos argumentos

In [13]:

# no
def funcion_01(x1,x2,x3,x4):
    print(x1,x2,x3,x4)
    
def funcion_02(
    x1,x2,x3,x4):
    print(x1,x2,x3,x4)

# no def funcion_01(x1,x2,x3,x4): print(x1,x2,x3,x4) def funcion_02( x1,x2,x3,x4): print(x1,x2,x3,x4)

In [14]:

# si
def funcion_01(x1,x2,
               x3,x4):
    
    print(x1,x2,x3,x4)
    
def funcion_02(
        x1,x2,
        x3,x4):
    
    print(x1,x2,x3,x4)

# si def funcion_01(x1,x2, x3,x4): print(x1,x2,x3,x4) def funcion_02( x1,x2, x3,x4): print(x1,x2,x3,x4)

Manipulación de listas¶

Aunque combinar iterables con elementos de control de flujo para manipular listas es muy sencillo con Python, hay métodos específicos más eficientes para hacer lo mismo. Pensemos el fitrado de datos de una lista:

In [15]:

# Seleccionar los números positivos
numeros = [-3, 2, 1, -8, -2, 7]
positivos = []
for i in numeros:
    if i > 0:
        positivos.append(i)
        
print(f"positivos: {positivos}")

# Seleccionar los números positivos numeros = [-3, 2, 1, -8, -2, 7] positivos = [] for i in numeros: if i > 0: positivos.append(i) print(f"positivos: {positivos}")

positivos: [2, 1, 7]

Aunque técnicamente es correcto, es más eficiente hacer List Comprehension:

In [16]:

# comprension de lista
numeros = [-3, 2, 1, -8, -2, 7]
positivos = [i for i in numeros if i > 0] # List Comprehension
print(f"positivos: {positivos}")

# comprension de lista numeros = [-3, 2, 1, -8, -2, 7] positivos = [i for i in numeros if i > 0] # List Comprehension print(f"positivos: {positivos}")

positivos: [2, 1, 7]

Especificar tipo de error¶

Cuando se ocupa try/except, es necesario especificar el tipo de error que se está cometiendo.

In [17]:

# importar librerias
import sys

# importar librerias import sys

In [18]:

# no
try:
    r = 1/0
except:
    print("Oops! ocurrio un",sys.exc_info()[0])

# no try: r = 1/0 except: print("Oops! ocurrio un",sys.exc_info()[0])

Oops! ocurrio un <class 'ZeroDivisionError'>

In [19]:

# si
try:
    r = 1/0
except ZeroDivisionError:
    print("Oops! ocurrio un",sys.exc_info()[0])

# si try: r = 1/0 except ZeroDivisionError: print("Oops! ocurrio un",sys.exc_info()[0])

Oops! ocurrio un <class 'ZeroDivisionError'>

Explicitar dependencias de una función¶

Siempre es mejor definir las variables dentro de una función y no dejar variables globales.

In [20]:

# no
valor = 5

def funcion_01(variable):
    return 2*variable + valor

# no valor = 5 def funcion_01(variable): return 2*variable + valor

In [21]:

funcion_01(2)

funcion_01(2)

Out[21]:

9

In [22]:

# si
def funcion_01(variable,valor):
    return 2*variable + valor

# si def funcion_01(variable,valor): return 2*variable + valor

In [23]:

funcion_01(2,5)

funcion_01(2,5)

Out[23]:

9

Escritura dinámica y estática¶

Con Python 3 se puede especificar el tipo de parámetro y el tipo de retorno de una función. Se definen dos conceptos claves:

• Escritura dinámica: no se especifican los atributos de los inputs ni de los ouputs
• Escritura estática: se especifican los atributos de los inputs y los ouputs

In [24]:

# escritura dinámica
def suma(x,y):
    return x+y

# escritura dinámica def suma(x,y): return x+y

In [25]:

print(suma(1,2))

print(suma(1,2))

3

In [26]:

# escritura estatica
def suma(x:float,
         y:float)->float:
    return x+y

# escritura estatica def suma(x:float, y:float)->float: return x+y

In [27]:

print(suma(1,2))

print(suma(1,2))

3

Para la escritura estática, si bien se especifica el tipo de atributo (tanto de los inputs o outputs), la función puede recibir otros tipos de atributos.

In [28]:

print(suma("hola"," mundo"))

print(suma("hola"," mundo"))

hola mundo

Para validar los tipos de datos son los correctos, se deben ocupar librerías especializadas en la validación de datos (por ejemplo pydantic).

Documentación de código¶

Casi tan importante como la escritura de código, es su correcta documentación, una parte fundamental de cualquier programa que a menudo se infravalora o simplemente se ignora. Aparte de los comentarios entre el código explicando cómo funciona, el elemento básico de documentación de Python es el Docstring o cadena de documentación, que ya hemos visto. Simplemente es una cadena de texto con triple comillas que se coloca justo después de la definición de función o clase que sirve de documentación a ese elemento.

In [29]:

def potencia(x, y):
    """
    Calcula la potencia arbitraria de un numero
    """
    return x**y

def potencia(x, y): """ Calcula la potencia arbitraria de un numero """ return x**y

In [30]:

# Acceso a la documentación
potencia.__doc__

# Acceso a la documentación potencia.__doc__

Out[30]:

'\n    Calcula la potencia arbitraria de un numero\n    '

In [31]:

# Acceso a la documentación
help(potencia)

# Acceso a la documentación help(potencia)

Help on function potencia in module __main__:

potencia(x, y)
    Calcula la potencia arbitraria de un numero

Lo correcto es detallar lo mejor posible en el Docstring qué hace y cómo se usa la función o clase y los parámetros que necesita. Se recomienda usar el estilo de documentación del software de documentación sphinx, que emplea reStructuredText como lenguaje de marcado.

Veamos un ejemplo de una función bien documentada:

In [32]:

def potencia(x, y):
    """
    Calcula la potencia arbitraria de un numero

    :param x: base
    :param y: exponente
    :return:  potencia de un numero
    :ejemplos:
    
    >>> potencia(2, 1)
    2
    >>> potencia(3, 2)
    9
    """

    return x**y

def potencia(x, y): """ Calcula la potencia arbitraria de un numero :param x: base :param y: exponente :return: potencia de un numero :ejemplos: >>> potencia(2, 1) 2 >>> potencia(3, 2) 9 """ return x**y

In [33]:

# Acceso a la documentación
potencia.__doc__

# Acceso a la documentación potencia.__doc__

Out[33]:

'\n    Calcula la potencia arbitraria de un numero\n\n    :param x: base\n    :param y: exponente\n    :return:  potencia de un numero\n    :ejemplos:\n    \n    >>> potencia(2, 1)\n    2\n    >>> potencia(3, 2)\n    9\n    '

In [34]:

# Acceso a la documentación
help(potencia)

# Acceso a la documentación help(potencia)

Help on function potencia in module __main__:

potencia(x, y)
    Calcula la potencia arbitraria de un numero
    
    :param x: base
    :param y: exponente
    :return:  potencia de un numero
    :ejemplos:
    
    >>> potencia(2, 1)
    2
    >>> potencia(3, 2)
    9

Tipos de Docstring

Existen varias formas de documentar tus funciones, las principales encontradas en la literatura son:

• Google docstrings:Google’s recommended form of documentation.
• reStructured Text:Official Python documentation standard; Not beginner friendly but feature rich.
• NumPy/SciPy docstrings:NumPy’s combination of reStructured and Google Docstrings.
• EpytextA Python adaptation of Epydoc; Great for Java developer."

Zen de python¶

El Zen de Python es un conjunto de principios y directrices que guían la escritura de código en el lenguaje de programación Python. Estas recomendaciones son presentadas de manera humorística y filosófica en el documento PEP 20 (Python Enhancement Proposal 20), que se puede obtener al ejecutar import this en un intérprete de Python. Aquí tienes algunas de las principales recomendaciones del Zen de Python:

1. Legibilidad cuenta: El código debe ser legible por los seres humanos y debe ser claro, conciso y fácil de entender.

2. Explícito es mejor que implícito: Es preferible que el código sea explícito en lugar de depender de comportamientos implícitos que pueden ser confusos.

3. Simple es mejor que complejo: Debes tratar de escribir código sencillo en lugar de complejo. La simplicidad facilita la depuración y el mantenimiento.

4. Plano es mejor que anidado: Evita anidar demasiados bloques de código. Niveles excesivos de anidación pueden hacer que el código sea difícil de seguir.

5. La legibilidad cuenta: Se repite la idea de que la legibilidad del código es crucial. Si el código es claro y legible, es más fácil de mantener y depurar.

6. Los errores nunca deben pasar en silencio: Los errores o excepciones no deben ser ignorados. Deben manejarse de manera adecuada y, si es necesario, registrarse para su posterior análisis.

7. En la duda, sigue el Zen de Python: Cuando tengas dudas sobre cómo escribir código de Python, consulta el Zen de Python para obtener orientación.

8. Hermoso es mejor que feo: Se fomenta la escritura de código limpio y elegante en lugar de código confuso o "feo".

9. Nunca te pases de listo: Evita escribir código excesivamente complejo o trucos innecesarios. La claridad es más importante que la astucia.

10. La simplicidad vence a la complejidad: Enfrenta los problemas de manera sencilla y evita soluciones innecesariamente complicadas.

Estas son solo algunas de las recomendaciones del Zen de Python. Estas pautas ayudan a los programadores a escribir código Python de manera consistente y a seguir buenas prácticas de programación.

También, podemos ver el mensaje original del zen de python, ejecutando la siguiente linea de comando.

In [35]:

import this

import this

The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

Más consejos¶

Los consejos que se presentan son de mucha utilidad si usted quiere llevar sus conociminetos de programación al siguiente nivel, sin embargo, el contenido de cada uno amerita un curso por si solo. Se deja recomienda al lector seguir profundizando en estos temas.

Entender programación multiparadigma¶

Python al ser multiparadigma, nos da una amplia gama de posibilidades de diseñar nuestros códigos. Dentro de estos se destacan:

• Programación orientada a objetos (OOP)
• Programación funcional

Cuándo ocupar uno o la otra, va a depender de cómo queremos abordar una determinada problemática, puesto que en la mayoría de los casos, se puede pasar de un paradigma a o otro (incluso mezclarlos de ser necesario).

Principio S.O.L.I.D¶

En ingeniería de software, SOLID (Single responsibility, Open-closed, Liskov substitution, Interface segregation and Dependency inversion) es un acrónimo mnemónico introducido por Robert C. Martin a comienzos de la década del 2000 que representa cinco principios básicos de la programación orientada a objetos y el diseño. Cuando estos principios se aplican en conjunto es más probable que un desarrollador cree un sistema que sea fácil de mantener y ampliar con el tiempo.

En el siguiente link se deja una guía para poder entender estos conceptos en python.

Patrones de diseño¶

Los patrones de diseño son la base para la búsqueda de soluciones a problemas comunes en el desarrollo de software y otros ámbitos referentes al diseño de interacción o interfaces.

Un patrón de diseño es una solución a un problema de diseño.

Se destacan tres tipos de patrones de diseños:

• Comportamiento
• Creacionales
• Estructurales

En el siguiente link se deja una guía para poder entender estos conceptos en python.

Lecturas recomendadas¶

• Clean Code: A Handbook of Agile Software - Robert C. Martin (2009): Habla sobre las buenas prácticas que debe seguir todo buen programador al momento de escribir su código. Si bien el lenguaje de programación emepleado es Java, la lógica se extiende a cualquier lenguaje de programación.

• The Clean Coder: A Code Of Conduct For Professional Programmers Robert C. Martin (2011): Habla sobre las conductas que debe seguir todo programador. Además de hablar aspectos técnicos como estimación, diseño de código, refactorización y testeos, también nos habla sobre la actitud que un programador debe tener en distintas situaciones laborales.

Referencias¶

1. clean-code-python
2. Documenting Python Code: A Complete Guide